Express 如何生成 API 文档？-JavaScript中文网-JavaScript教程资源分享门户

推荐答案

在 Express 中生成 API 文档的推荐方式是使用 swagger-jsdoc 和 swagger-ui-express 这两个库。swagger-jsdoc 可以通过在代码中添加注释来生成 OpenAPI 规范的文档，而 swagger-ui-express 则可以将生成的文档以可视化的形式展示出来。

安装依赖

首先，安装所需的依赖：

npm install swagger-jsdoc swagger-ui-express

配置 Swagger

在 Express 应用中配置 Swagger：

// 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: 'API 文档',
      version: '1.0.0',
      description: 'API 文档示例',
    },
    servers: [
      {
        url: 'http://localhost:3000',
        description: '本地服务器',
      },
    ],
  },
  apis: ['./routes/*.js'], // 指定包含 API 文档注释的文件路径
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerDocs));

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

添加 API 文档注释

在路由文件中添加 Swagger 注释：

// 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' }]);
});

访问 API 文档

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

本题详细解读

1. 为什么选择 Swagger？

Swagger 是一个广泛使用的 API 文档工具，支持 OpenAPI 规范。通过 Swagger，开发者可以在代码中直接添加注释来生成 API 文档，而不需要额外维护文档文件。这种方式不仅减少了文档与代码不一致的风险，还能通过 swagger-ui-express 提供友好的可视化界面。

2. `swagger-jsdoc` 的作用

swagger-jsdoc 是一个用于生成 OpenAPI 规范的库。它通过解析代码中的 JSDoc 注释来生成符合 OpenAPI 规范的 JSON 或 YAML 文件。开发者只需要在代码中添加特定的注释，swagger-jsdoc 就会自动生成文档。

3. `swagger-ui-express` 的作用

swagger-ui-express 是一个用于在 Express 应用中展示 Swagger 文档的中间件。它将生成的 OpenAPI 规范文档以可视化的形式展示出来，提供了一个交互式的 API 文档界面，开发者可以直接在浏览器中测试 API。

4. 如何维护 API 文档

通过 swagger-jsdoc 生成的 API 文档与代码紧密耦合，因此当代码发生变化时，文档也会自动更新。这种方式确保了文档的实时性和准确性，减少了手动维护文档的工作量。

5. 其他替代方案

除了 Swagger，还有其他一些工具可以用于生成 API 文档，如 apidoc 和 postman。然而，Swagger 由于其强大的功能和广泛的社区支持，通常是首选方案。

通过以上步骤，你可以在 Express 应用中轻松生成并维护 API 文档。

Express 如何生成 API 文档？