在编写大型 Express 应用程序时，管理 API 文档可能会变得非常困难。为此，我们可以使用 express-docs-keeper 这个 npm 包，以轻松地生成和管理 API 文档。在本文中，我们将详细讲解如何使用这个包。
安装
首先，使用 npm 进行安装：
npm install express-docs-keeper
创建并配置 swagger.json 文件
在使用 express-docs-keeper 之前，我们需要创建一个包含接口描述信息的 swagger.json 文件。我们可以使用 Swagger Editor 或类似工具来创建和编辑这个文件。
在编辑 swagger.json 文件时，请确保填写每个接口需要的信息，例如：
-- -------------------- ---- ------- - ---------- ------ ------- - ---------- -------- -------- -------- ----- -------------- ----- -- -- ------- ----- -- ----------- ------- -------- - --------- - ------ - ---------- ---- - ---- -- ------- ------- - ------- -- ------------ - ------ - -------------- ----------- ---------- --------- - ------- -------- -------- - ------- --------- ------------- - ----- - ------- --------- -- ------- - ------- -------- - -- ----------- - ----- ------ - - - - - - - - -展开代码
配置 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 时，请注意以下几点：
- 在 swagger.json 文件中，请务必填写每个接口需要的信息，包括接口描述、返回值类型等等。
- express-docs-keeper 仅支持基于 Swagger 的 API 文档，如果你使用其他格式的 API 文档，请先将它转换成 Swagger。
- 如果你的应用程序中的接口发生了变化，你需要及时更新 swagger.json 文件。
结论
在 Express 应用程序中管理和生成 API 文档是一项非常重要的任务，我们可以使用 express-docs-keeper 这个 npm 包来实现这一任务。在本文中，我们详细讲解了如何使用这个包，并提供了示例代码。如果你正在开发一些大型的 Express 应用程序，我相信这个包能够让你的工作更加轻松和高效。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60056be881e8991b448e5a21
