利用Swagger生成express接口文档

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

主要利用这两个包：

swagger-jsdoc：可以将注释中的 API 文档生成 Swagger 格式的文档
swagger-ui-express：在浏览器中展示接口文档

步骤#

1. 安装 npm 包#

1
npm install swagger-jsdoc swagger-ui-express

2. Swagger 配置#

在项目根目录创建 swagger/swaggerDocs.js 配置文件，用于定义 swagger 配置：

1
import swaggerJsdoc from 'swagger-jsdoc'
2

3
const swaggerOptions = {
4
  definition: {
5
    openapi: '3.0.0',
6
    info: {
7
      title: 'Express API with Swagger', //  title: API 的标题
8
      version: '1.0.0', // version: API 的版本号
9
      description: 'A simple CRUD API application with Express and Swagger', // description: API 的描述信息
10
    },
11
    servers: [
12
      {
13
        url: 'http://localhost:3000',
14
      },
15
    ],
16
  },
17
  apis: ['./routes/**/*.js'], // 使用了 './routes/**/*.js'，这会匹配 routes 文件夹及其所有子文件夹中的所有 .js 文件
18
}
19

20
const swaggerDocs = swaggerJsdoc(swaggerOptions)
21

22
export default swaggerDocs

通过这些配置，swagger-jsdoc 将扫描指定的路由文件，解析其中的 Swagger 注释，并生成对应的 Swagger 文档。这些文档可以通过 swagger-ui-express 在浏览器中进行可视化展示。

3. 在 app.js 引入 swagger#

1
...
2
import swaggerUi from 'swagger-ui-express'
3
import swaggerDocs from './swagger/swaggerConfig'
4

5

6
// 使用 Swagger
7
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
8
...

此时访问 localhost:3000/api-docs 就可以看到 Swagger 页面（还没有配置，所以接口为空）

4. 在 router 中配置接口文档信息#

在路由文件中添加 Swagger 注释

Swagger 注释是一种在代码中嵌入文档信息的方式，用于描述 API 的各个方面，包括路径、方法、参数、响应等。Swagger 通过解析这些注释来生成 API 文档，因此注释的格式和规则非常重要。下面是 Swagger 注释的一些基本规则和常用标记：

基本规则

1
1. 基本结构：
2
•  Swagger 注释以 @swagger 或 @openapi 开头，后面紧跟着 YAML 或 JSON 格式的文档信息。
3
2. 路径和方法：
4
•  使用 @swagger 标记来描述 API 路径和方法。例如：

1
/**
2
 * @swagger
3
 * /users:
4
 *   get:
5
 *     summary: 获取所有用户
6
 *     description: 返回所有用户列表
7
 */

参数和响应： • 描述请求参数和响应体的结构和类型。可以使用 parameters 和 responses 来定义。

1
/**
2
 * @swagger
3
 * /users:
4
 *   get:
5
 *     summary: 获取所有用户
6
 *     parameters:
7
 *       - name: id
8
 *         in: query
9
 *         required: true
10
 *         type: string
11
 *         description: 用户ID
12
 *     responses:
13
 *       '200':
14
 *         description: 成功获取用户列表
15
 *         schema:
16
 *           type: array
17
 *           items:
18
 *             $ref: '#/definitions/User'
19
 */

1
5.  其他常用标记：
2
•  @summary：API 摘要或简要描述。
3
•  @description：详细描述 API 的作用和功能。
4
•  @param：描述函数或方法的参数。
5
•  @returns 或 @return：描述函数或方法的返回值。
6
•  @deprecated：标记 API 已弃用。

音乐

音乐

步骤#

1. 安装 npm 包#

2. Swagger 配置#

3. 在 app.js 引入 swagger#

4. 在 router 中配置接口文档信息#

音乐

文章目录