Express中使用Swagger

Swagger

Swagger 是一种规范，用于描述 API 的结构，功能和参数。使用 Swagger 可以提供清晰的可视化 API 文档，可用于 API 交互的文档驱动开发，以及 API 的自动化测试和集成。

1. 使用 npm 或 yarn 下载。

npm install swagger-jsdoc swagger-ui-express --save

yarn add swagger-jsdoc swagger-ui-express

2. 在 Express 根目录下的 app.js 中导入。

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

// ...

// definition 字段用于定义 Swagger 规范，apis 字段用于指定使用 Swagger 规范的 API 文件路径
const options = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: 'My API',
            version: '1.0.0'
        }
    },
    apis: ['./routes/*.js']
};

const swaggerSpec = swaggerJsdoc(options);

app.use('/api', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// 其他路由...

3. 导入后即可在 router 中新增 Swagger 注释。

/**
 * @swagger
 * /users:
 *  get:
 *    summary: 获取所有用户信息
 *    responses:
 *      200:
 *        description: 成功获取所有用户信息
 * 
 *  post:
 *    summary: 创建用户
 *    parameters:
 *      - in: body
 *        name: user
 *        schema:
 *          type: object
 *          properties:
 *            name:
 *              type: string
 *            age:
 *              type: integer
 *    responses:
 *      200:
 *        description: 成功创建用户
 */

如果编写接口时使用的是 ApiFox 或 PostCat 等支持导出 OpenAI 规范文件的接口工具，
可以导出 OpenAI 规范的接口文件，然后访问 Swagger Editor 并导入接口文件。将左侧显示的内容复制到 Express 的路由文件中，并调整格式如上文所示注释格式即可。

跳转 Express 下的 /api 即可访问所有使用 Swagger 规范的 API 接口。