如何使用 Swagger (OpenAPI) 生成 Express API 文档？

推荐答案

// www.javascriptcn.com code example
const express = require('express');
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const app = express();

// Swagger 配置
const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'Express API',
      version: '1.0.0',
      description: 'Express API 文档',
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: '本地服务器',
      },
    ],
  },
  apis: ['./routes/*.js'], // 指定包含 API 文档注释的文件路径
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);

// 使用 Swagger UI 提供 API 文档
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

// 启动服务器
app.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
  console.log('API 文档运行在 http://localhost:3000/api-docs');
});

本题详细解读

1. 安装依赖

首先，你需要安装 swagger-jsdoc 和 swagger-ui-express 这两个包：

npm install swagger-jsdoc swagger-ui-express

• swagger-jsdoc：用于从代码注释中生成 Swagger 文档。
• swagger-ui-express：用于在 Express 应用中提供 Swagger UI 界面。

2. 配置 Swagger

在代码中，swaggerOptions 对象用于配置 Swagger 文档的基本信息，包括 API 的版本、描述、服务器地址等。apis 字段指定了包含 API 文档注释的文件路径，通常是指向你的路由文件。

3. 生成 Swagger 文档

通过 swaggerJsDoc(swaggerOptions) 生成 Swagger 文档对象 swaggerDocs。

4. 提供 Swagger UI

使用 swaggerUi.serve 和 swaggerUi.setup(swaggerDocs) 将 Swagger UI 集成到 Express 应用中，并通过 /api-docs 路径访问。

5. 启动服务器

最后，启动 Express 服务器，并访问 http://localhost:3000/api-docs 查看生成的 API 文档。

6. 编写 API 文档注释

在你的路由文件中，使用 JSDoc 注释来描述 API 的各个部分。例如：

// www.javascriptcn.com code example
/**
 * @swagger
 * /users:
 *   get:
 *     summary: 获取用户列表
 *     description: 返回所有用户的列表
 *     responses:
 *       200:
 *         description: 成功获取用户列表
 */
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'John Doe' }]);
});

通过这种方式，Swagger 会自动生成 API 文档，并在 Swagger UI 中展示。