如何基于swagger-ui-express与swagger-jsdoc自动生成模型的Schema Definitions？

针对你用swagger-jsdoc和swagger-ui-express的场景，有几种实用的方式可以自动生成Schema Definitions，不用手动编写JSON：

方法1：通过JSDoc注释直接定义Schemas #

这是swagger-jsdoc原生支持的方式，你可以在单独的文件里用@swagger注释定义所有模型，然后让工具自动扫描加载这些定义。

步骤： #

1. 创建一个专门存放Schema定义的文件，比如./models/swagger-schemas.js：

/**
 * @swagger
 * definitions:
 *   ApiResponse:
 *     type: object
 *     properties:
 *       code:
 *         type: integer
 *         format: int32
 *       type:
 *         type: string
 *       message:
 *         type: string
 *   Category:
 *     type: object
 *     properties:
 *       id:
 *         type: integer
 *         format: int64
 *       name:
 *         type: string
 *     xml:
 *       name: Category
 */

2. 更新你的swaggerOptions，把这个文件加入到apis数组中：

const swaggerOptions = {
  swaggerDefinition: {
    info: {
      title: 'My API',
      version: '1.0.0',
    },
    servers: ['http://localhost:8000'],
  },
  // 加入新的Schema定义文件
  apis: ['./routes/*.js', './models/swagger-schemas.js'],
};

3. 在路由注释中引用这些定义：

/**
 * @swagger
 * /user/get/all:
 *  get:
 *    summary: Get all users
 *    responses:
 *      '200':
 *        description: successful operation
 *        schema:
 *          type: array
 *          items:
 *            $ref: '#/definitions/Category'
 */

启动项目后，/api-docs页面就会自动加载这些Schema Definitions了。

方法2：从ORM模型自动生成（比如Mongoose/Sequelize） #

如果你用了ORM框架（比如Mongoose），可以用工具把数据库模型直接转换成Swagger Schemas，避免重复编写。

以Mongoose为例：

1. 安装转换工具mongoose-to-swagger：

npm install mongoose-to-swagger

2. 在你的Swagger配置中引入模型并转换：

const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const mongooseToSwagger = require('mongoose-to-swagger');
// 引入你的Mongoose模型
const Category = require('./models/Category');
const User = require('./models/User');

const swaggerOptions = {
  swaggerDefinition: {
    info: {
      title: 'My API',
      version: '1.0.0',
    },
    servers: ['http://localhost:8000'],
    // 自动生成definitions
    definitions: {
      Category: mongooseToSwagger(Category),
      User: mongooseToSwagger(User),
      // 其他模型同理
    }
  },
  apis: ['./routes/*.js'],
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

这样你的Mongoose模型字段会被自动转换成Swagger的Schema定义，后续修改模型时，Swagger文档也会同步更新。

方法3：使用@typedef注释定义Schemas #

swagger-jsdoc也支持用JSDoc的@typedef和@property注释来定义模型，这种方式更贴近普通JSDoc风格：

1. 在任意被apis数组包含的文件中添加：

/**
 * @typedef ApiResponse
 * @property {integer} code - 响应状态码
 * @property {string} type - 响应类型
 * @property {string} message - 响应信息
 */

/**
 * @typedef Category
 * @property {integer} id - 分类ID
 * @property {string} name - 分类名称
 */

2. 同样在路由注释中通过$ref引用：

/**
 * @swagger
 * /user/get/all:
 *  get:
 *    summary: Get all users
 *    responses:
 *      '200':
 *        description: successful operation
 *        schema:
 *          $ref: '#/definitions/ApiResponse'
 */

swagger-jsdoc会自动把这些@typedef转换成Swagger的definitions。

内容的提问来源于stack exchange，提问作者Carolina