使用 express-docs-keeper 管理你的 Express API 文档

在编写大型 Express 应用程序时，管理 API 文档可能会变得非常困难。为此，我们可以使用 express-docs-keeper 这个 npm 包，以轻松地生成和管理 API 文档。在本文中，我们将详细讲解如何使用这个包。

安装

首先，使用 npm 进行安装：

npm install express-docs-keeper

创建并配置 swagger.json 文件

在使用 express-docs-keeper 之前，我们需要创建一个包含接口描述信息的 swagger.json 文件。我们可以使用 Swagger Editor 或类似工具来创建和编辑这个文件。

在编辑 swagger.json 文件时，请确保填写每个接口需要的信息，例如：

// www.javascriptcn.com code example
{
  "swagger": "2.0",
  "info": {
    "version": "0.0.1",
    "title": "Example API",
    "description": "This is an example API."
  },
  "basePath": "/api",
  "paths": {
    "/users": {
      "get": {
        "summary": "Get a list of users",
        "tags": [
          "Users"
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "schema": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "name"
                ]
              }
            }
          }
        }
      }
    }
  }
}

配置 Express 应用程序

接下来，我们需要在 Express 应用程序中配置 express-docs-keeper。我们需要导入以下模块：

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerFile = require('./swagger.json');
const expressDocsKeeper = require('express-docs-keeper');

接下来，我们需要把 swagger.json 文件传递给 express-docs-keeper，让它生成路由和中间件：

const router = expressDocsKeeper(swaggerFile);

现在，我们需要将路由连接到应用程序，并指定输出 API 文档的端点：

app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerFile));
app.use('/api', router);

最后，我们需要在应用程序上监听端口：

app.listen(3000, () => console.log('Server started on port 3000'));

运行

现在我们的 Express 应用程序已准备好，我们可以运行它并查看生成的 API 文档。打开浏览器，访问 http://localhost:3000/docs，即可看到生成的 API 文档。

使用 express-docs-keeper 前的注意事项

在使用 express-docs-keeper 时，请注意以下几点：

1. 在 swagger.json 文件中，请务必填写每个接口需要的信息，包括接口描述、返回值类型等等。
2. express-docs-keeper 仅支持基于 Swagger 的 API 文档，如果你使用其他格式的 API 文档，请先将它转换成 Swagger。
3. 如果你的应用程序中的接口发生了变化，你需要及时更新 swagger.json 文件。

结论

在 Express 应用程序中管理和生成 API 文档是一项非常重要的任务，我们可以使用 express-docs-keeper 这个 npm 包来实现这一任务。在本文中，我们详细讲解了如何使用这个包，并提供了示例代码。如果你正在开发一些大型的 Express 应用程序，我相信这个包能够让你的工作更加轻松和高效。

Source: FunTeaLearn,Please indicate the source for reprints https://funteas.com/post/60056be881e8991b448e5a21