尝试将 OpenAPI 中的 $ref 应用于我的用例

Question

所以我正在尝试为我的 OpenApi 文档应用 $ref，但我不确定我是否正确应用它，到目前为止，我的一个端点看起来像这样：

/**
 * @openapi
 * /api/v2/auth/permissions:
 *   get:
 *     description: Get permissions
 *     responses:
 *       200:
 *         description: Get permissions.
 *         content:
 *         application/json:
 *           schema:
 *             $ref: './model/permission.model'
 */

这只会输出这样的字符串："string".

如果您需要查看该模型文件或其他任何内容，请告诉我。

permission.model.ts 文件如下所示：

interface Permission {
  _id: ID,

  roleId?: string,
  userId?: number,
  groupId?: number
}

const PermissionSchemaFields: Record<keyof Permission, any> = {
  _id: Types.ObjectId,

  roleId: { type: String, required: false }
  userId: { type: Number, required: false }
  groupId: { type: Number, required: false }
}

const PermissionSchema = new Schema(
  PermissionSchemaFields,
  { timestamps: { createdAt: 'createdOn', updatedAt: 'updatedOn'}}
);

export {PermissionSchema, Permission}

Answer 1

我错误地认为在定义 $ref 时我必须做一些与文档所说不同的事情，但那部分必须是相同的，如下所示：

/**
 * @openapi
 * /api/v2/auth/permissions:
 *   get:
 *     description: Get permissions
 *     responses:
 *       200:
 *         description: Get permissions.
 *         content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/PermActionSchemaFields'
 */

然后在 permaction.model.ts 文件中，我仍然必须在 PermActionSchemaFields 函数上方添加另一个这些注释掉的块，如下所示：

/**
* @openapi
* components:
*   schemas:
*     PermActionSchemaFields:
*       type: object
*       required:
*         - _id
*         - permActionType
*         - description
*         - createdOn
*         - updatedOn
*         - __v
*       properties:
*         schemaVersion:
*           type: string
*         _id:
*           type: string
*           description:
*         permActionType:
*           type: string
*           description:
*         description:
*           type: string
*           description:
*         createdOn:
*           type: string
*           description:
*         updatedOn:
*           type: string
*         __v:
*           type: number
*       example:
*         schemaVersion: 1
*         _id: post /api/v2/patients
*         permActionType: SyncApi
*         description: RESTful endpoint POST /api/v2/patients
*         createdOn: 2021-07-16T21:30:33.624Z
*         updatedOn: 2021-07-16T21:30:33.624Z
*         __v: 0
*/

尝试将 OpenAPI 中的 $ref 应用于我的用例

Trying to apply $ref from OpenAPI to my use case

swagger

openapi