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 接口。