Express.js 是一个广泛使用的 Node.js Web 应用程序框架，被许多中大型网站使用。在开发过程中，为了方便维护，我们需要自动生成 Express.js 应用程序的 API 文档。这样，团队成员就可以知道每个 API 的功能和用法，并且可以避免重复编写文档的问题。本文将介绍如何使用 JavaScript 和一些工具自动生成 Express.js API 文档，并提供示例代码。
安装和配置 swagger-jsdoc
首先，我们需要安装一个名为 swagger-jsdoc 的包。swagger-jsdoc 可以帮助我们自动生成 Express.js 应用程序的 Swagger 规范。Swagger 规范提供了一种定义 API 行为、参数、响应格式等的标准化方法。 推荐使用 Yarn 或 npm 安装 swagger-jsdoc。
npm install --save-dev swagger-jsdoc
然后，在 Swagger 规范中，我们需要为每个 API 写入一些注释才能生成 API 文档。在 Express.js 应用程序中，可以使用注释来定义每个路由。以下是示例路由和注释：
-- -------------------- ---- ------- --- - -------- - ------- - ---- - -------- --- --- ----- - ------------ -------- - ---- -- --- ----- - ---------- - ---- - ------------ - ---- -- ----- - -------- - ----------------- - ------- - ----- ----- - ------ - ----- --------------------------- -- ----------------- -------- ----- ---- - -- --- ---
上述注释可以告诉 Swagger 规范如何定义 API 的行为、参数以及响应格式。
生成 JSON 文件
现在我们已经定义了所有的注释，下一步是将这些注释生成为 JSON 文件。为此，我们可以使用 swagger-jsdoc 提供的功能。下面是一个示例：
-- -------------------- ---- -------
----- ------------ - -------------------------
----- ------- - -
----------- -
-------- --------
----- -
------ -------- --- ---- ---------
-------- --------
------------
----- -- - ------ ------- --- ---- ------- ----------------
--------------- ----------------------------
-------- -
----- ---- ---------
---- ---------------------------------
------ ----------------------
--
-------- -
----- ------- -----
---- ---------------------------------------------------
--
--
-------- -
-
---- ------------------------
------------ ------------ --------
--
--
--
----- ------------------
--
----- ----------- - ----------------------在以上示例中，我们定义了 Swagger 规范的基本信息、服务器信息以及 API 路径信息。参数 apis 可以指定包含注释的路由文件目录。
安装 swagger-ui-express
现在，我们已经生成了 Swagger 规范的 JSON 文件，下一步是将其呈现给用户。Swagger UI 是一种交互式的工具，用于帮助用户浏览和使用 API。我们可以使用 swagger-ui-express 包安装 Swagger UI。swagger-ui-express 是一个可在 Express.js 应用程序中使用的包，它提供了一个轻量级 UI，可以显示 Swagger 规范的 JSON 文件。 推荐使用 Yarn 或 npm 安装 swagger-ui-express。
npm install --save swagger-ui-express
为了将 Swagger UI 显示为 Web UI，我们需要在 Express.js 应用程序中设置中间件，并告诉它从哪个 URL 获取 Swagger 规范的 JSON 文件。以下是示例中间件代码：
const swaggerUi = require('swagger-ui-express');
const express = require('express');
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));在上述示例代码中，我们设置了一个 /api-docs 路由，该路由将 Swagger UI 显示为 Web UI。注意，我们需要导入 swaggerSpec 变量，这是一个包含我们生成的所有注释和 Swagger 规范信息的 JSON 文件。
示例代码
为了简化设置和教育，以下是完整的示例代码：
-- -------------------- ---- -------
----- ------------ - -------------------------
----- --------- - ------------------------------
----- ------- - -------------------
----- --- - ----------
----- ------- - -
----------- -
-------- --------
----- -
------ -------- --- ---- ---------
-------- --------
------------
----- -- - ------ ------- --- ---- ------- ----------------
--------------- ----------------------------
-------- -
----- ---- ---------
---- ---------------------------------
------ ----------------------
--
-------- -
----- ------- -----
---- ---------------------------------------------------
--
--
-------- -
-
---- ------------------------
------------ ------------ --------
--
--
--
----- ------------------
--
----- ----------- - ----------------------
-------------------- ---------------- ------------------------------
---------------- -- -- -
-------------------- --- --------- -- ---- --------
---总结
本文介绍了如何使用 swagger-jsdoc 和 swagger-ui-express 生成 Express.js 应用程序的 API 文档，并提供了代码示例。自动生成 API 文档可以帮助我们提高开发效率，减少文档重复编写的问题，并使团队成员更容易理解 API 的用法。在实际项目中，我们可以根据自己的需要修改 Swagger 规范的定义，以确保文档的准确性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/648e58f148841e9894cb30a5
