Node.js 集成 Swagger 生成 JWT 接口文档

脚本专家

Swagger 在 Node.js/Express 项目中的常见落地方式是：swagger-jsdoc 把路由文件里的 JSDoc 注释转成 OpenAPI 规范，swagger-ui-express 把规范渲染成可交互的 API 文档页面。原文以用户管理 API 为例，使用 OpenAPI 3.0.0，扫描路径为 ./src/routes/*.js，文档挂载到 /api-docs，并通过 bearerAuth 声明 JWT 认证。

一、安装依赖

2. npm install swagger-jsdoc swagger-ui-express

复制代码

其中 swagger-jsdoc 负责把 JSDoc 注释转换为 Swagger/OpenAPI 规范，swagger-ui-express 负责提供 Swagger UI 界面。

二、配置 src/config/swagger.js
核心配置包括 openapi 版本、info 信息、servers、securitySchemes、schemas、tags、security 和 apis 扫描路径。原文在 components.schemas 中还定义了 LoginResponse、UserListResponse、User、CreateUserRequest 等结构，下面保留核心配置结构：

2. // src/config/swagger.js
3. const swaggerJsdoc = require('swagger-jsdoc')
4. const options = {
5.   definition: {
6.     openapi: '3.0.0',
7.     info: {
8.       title: '用户管理 API 文档',
9.       version: '1.0.0',
10.       description: '基于 Express + JWT 的用户管理接口文档',
11.       contact: { name: 'API Support', email: 'support@example.com' },
12.       license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' }
13.     },
14.     servers: [
15.       { url: 'http://localhost:3000/api', description: '开发服务器' },
16.       { url: 'https://api.example.com/api', description: '生产服务器' }
17.     ],
18.     components: {
19.       securitySchemes: {
20.         bearerAuth: {
21.           type: 'http',
22.           scheme: 'bearer',
23.           bearerFormat: 'JWT',
24.           description: '输入 Bearer Token'
25.         }
26.       },
27.       schemas: {
28.         ApiResponse: {
29.           type: 'object',
30.           properties: {
31.             code: { type: 'integer', description: '状态码：0-成功，其他-失败', example: 0 },
32.             msg: { type: 'string', description: '响应消息', example: '操作成功' },
33.             data: { type: 'object', description: '响应数据' }
34.           }
35.         },
36.         LoginRequest: {
37.           type: 'object',
38.           required: ['username', 'password'],
39.           properties: {
40.             username: { type: 'string', description: '用户名', example: 'admin' },
41.             password: { type: 'string', description: '密码', example: '123456' }
42.           }
43.         }
44.       }
45.     },
46.     security: [{ bearerAuth: [] }],
47.     tags: [
48.       { name: '认证', description: '用户认证相关接口' },
49.       { name: '用户管理', description: '用户管理相关接口' }
50.     ]
51.   },
52.   apis: ['./src/routes/*.js']
53. }
54. module.exports = swaggerJsdoc(options)

复制代码

三、在 app.js 中集成 Swagger UI

2. const express = require('express')
3. const cors = require('cors')
4. require('dotenv').config()
5. const swaggerUi = require('swagger-ui-express')
6. const swaggerSpec = require('./config/swagger')
7. const authRoutes = require('./routes/auth')
8. const userRoutes = require('./routes/user')
9. const app = express()
10. const PORT = process.env.PORT || 3000
11. app.use(cors())
12. app.use(express.json())
13. app.use(express.urlencoded({ extended: true }))
14. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec, {
15.   explorer: true,
16.   customCss: '.swagger-ui .topbar { display: none }',
17.   customSiteTitle: '用户管理 API 文档',
18.   swaggerOptions: { persistAuthorization: true }
19. }))
20. app.get('/api-docs.json', (req, res) => {
21.   res.setHeader('Content-Type', 'application/json')
22.   res.send(swaggerSpec)
23. })
24. app.use('/api/auth', authRoutes)
25. app.use('/api/user', userRoutes)
26. app.listen(PORT, () => {
27.   console.log(`服务器地址: http://localhost:${PORT}`)
28.   console.log(`Swagger 文档: http://localhost:${PORT}/api-docs`)
29. })

复制代码

这里 explorer 用于显示搜索框，customCss 隐藏顶部栏，customSiteTitle 设置页面标题，persistAuthorization 持久化认证信息；/api-docs.json 可导出 Swagger 规范给其他工具使用。

四、在路由中写 JSDoc 注释
认证路由的登录接口可按如下方式声明请求体和响应：

2. /**
3. * @swagger
4. * /auth/login:
5. *   post:
6. *     summary: 用户登录
7. *     description: 使用用户名和密码登录，返回 JWT Token
8. *     tags: [认证]
9. *     requestBody:
10. *       required: true
11. *       content:
12. *         application/json:
13. *           schema:
14. *             $ref: '#/components/schemas/LoginRequest'
15. *     responses:
16. *       200:
17. *         description: 登录成功
18. *         content:
19. *           application/json:
20. *             schema:
21. *               $ref: '#/components/schemas/LoginResponse'
22. *       400:
23. *         description: 请求参数错误
24. *       401:
25. *         description: 用户名或密码错误
26. *       403:
27. *         description: 用户已被禁用
28. */
29. router.post('/login', async (req, res) => {
30.   // ... 原有代码
31. })

复制代码

用户列表接口需要声明 security 和 query 参数，参数含义包括 page 页码、size 每页大小、keyword 关键词搜索、status 状态 0/1、role 角色枚举：

2. /**
3. * @swagger
4. * /user/list:
5. *   get:
6. *     summary: 获取用户列表
7. *     tags: [用户管理]
8. *     security:
9. *       - bearerAuth: []
10. *     parameters:
11. *       - in: query
12. *         name: page
13. *         schema: { type: integer, default: 1 }
14. *         description: 页码
15. *       - in: query
16. *         name: size
17. *         schema: { type: integer, default: 10 }
18. *         description: 每页大小
19. *       - in: query
20. *         name: keyword
21. *         schema: { type: string }
22. *         description: 关键词搜索（用户名或邮箱）
23. *       - in: query
24. *         name: status
25. *         schema: { type: integer, enum: [0, 1] }
26. *         description: 用户状态：0-禁用，1-启用
27. *       - in: query
28. *         name: role
29. *         schema: { type: string, enum: [admin, manager, user, developer] }
30. *         description: 用户角色
31. *     responses:
32. *       200:
33. *         description: 获取用户列表成功
34. *         content:
35. *           application/json:
36. *             schema:
37. *               $ref: '#/components/schemas/UserListResponse'
38. *       400:
39. *         description: 请求参数错误
40. *       401:
41. *         description: 未登录或 Token 无效
42. */
43. router.get('/list', authenticate, (req, res) => {
44.   // ... 原有代码
45. })

复制代码

五、访问与调试
启动服务后访问 http://localhost:3000/api-docs。Swagger UI 顶部提供搜索框，左侧按 Tags 分组显示接口，右侧显示选中接口的详细信息。需要 Token 的接口先点击右上角 Authorize，输入 Bearer <你的Token> 并确认。测试接口时展开目标接口，点击 Try it out，填写参数后点击 Execute 查看响应结果。原文还列出的导出方案包括使用 swagger-to-markdown 以及通过 Swagger Editor 导出 Markdown/PDF；常见问题部分列出了 Swagger 页面空白、JSDoc 注释没有被解析、Swagger 中显示不了中文三类现象。

整体上，这种写法的关键是让路由注释、swagger.js 中的 schemas 定义和实际接口实现保持同步；接口路径、参数、JWT 认证声明一旦变化，也要同步修改对应 JSDoc 注释，否则最终渲染出的 API 文档会与实现不一致。