在开发 RESTful API 的过程中，生成文档可能是一项让人感到繁琐的任务。为了提高文档的质量和可读性，我们需要一个工具来实现这个目标。Swagger 就是这样一款能够自动生成 RESTful API 文档的工具。
什么是 Swagger？
Swagger 是一个开源工具集，用于创建、编写和部署 RESTful API 的文档。它提供了一组用于定义 API 的约定和规范，这些约定和规范可以使用 JSON 或 YAML 格式来描述 API。Swagger 的目标是为开发者和用户创造更好的 API 体验。
使用 Swagger 构建 API 文档
- 安装 Swagger
可以使用 npm 来安装 Swagger，命令如下所示：
npm install -g swagger
- 创建新项目
创建一个新的项目，例如一个基于 Node.js 的 RESTful API 项目，在命令行中输入以下命令：
swagger project create api-project
这将使用 Swagger 的默认配置文件创建一个新的项目目录，其中包含了 API 的基本结构和必要的依赖。
- 定义 API
接下来，我们需要使用 YAML 或 JSON 文件编写 API 文档。在项目文件夹中创建一个新文件，例如 api.yaml。在这个文件中，使用 Swagger 指定 API 的端点、参数、请求和响应格式等信息。
以下是一个基本的示例：
-- -------------------- ---- -------
-------- -----
-----
------ -- ---
-------- -----
------
-------
----
-------- --- --- -----
---------
- ----------------
----------
----
------------ --
----
------------ -------- ------ -----在这个示例中，我们定义了一个名为“/users”的端点，使用 GET 方法获取所有用户。我们还定义了响应格式为 JSON，并在响应中包含了一个 OK 和一个 Internal Server Error。
- 部署 API 文档
使用以下命令来启动 API 文档：
swagger project start
Swagger 将在 http://localhost:10010/ 上启动一个本地服务器，并自动创建一个交互式文档。
使用 Swagger UI
Swagger UI 是 Swagger 特有的 API 文档生成工具。它是一个跨平台（支持 PC 和移动设备）的网页应用，可以自动地根据 Swagger 规范显示和构建 API 文档。
要使用 Swagger UI，需要在 HTML 标记中插入一个 JavaScript 文件，并将 Yml 或 Json 格式的 Swagger 规范文件输入。
以下是 Swagger UI 的一些示例代码：
嵌入式 Swagger UI
-- -------------------- ---- -------
--------- -----
----- ----------
------
----- --------------- --
--------- --- ---------------------
----- ---------------- --------------- ---------------------------------------------------- --
-------
------
---- ----------------------
------- -------------------------------------------------------------------
------- ------------------------------------------------------------------------------
--------
----- -- - -----------------
---- -----------
------- --------------
------------ -----
-------- -------------------------------
-------- --------------------------------------
------- -------------------
---
---------
-------
-------在这个示例中，我们通过引用 Swagger UI 相关的 CSS 和 JavaScript 的源文件从而在我们的 HTML 中嵌入了一个 Swagger UI。
然后，我们定义了一个 JavaScript 变量（即 ui，用于后续的操作），通过以下方式设置其他配置选项：
url- Yml 或 Json 格式的 Swagger 规范文件的本地或远程 URI。dom_id- Swagger UI 顶级 DOM 元素的 ID。deepLinking- 是否启用深层链接（通过设置 URL 中的“#”符号来从 Swagger UI 中导航）。presets- 在 Swagger UI 中启用的插件集。plugins- 响应式显示，不同文档下载链接等插件的列表。layout- 由 Webpack 生成的 Swagger UI 应用程序的布局将使用的布局的类型。
基于 Node.js 的 Swagger UI
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));在这个例子中，我们将生成的 Swagger 规范文件捆绑为一个 JSON 文件，并在 Node.js 中通过使用 Swagger UI Express 中间件来设置路由和 API 文档的位置。在 Node.js 应用程序的根目录中设置一个API 文档，可以通过 npm start 在 localhost:3000 访问。
总结
Swagger 是一个非常好用的 API 文档生成工具。它广泛支持成熟的 API 标准解决方案，而且非常易于使用。通过使用 Swagger，开发者可以轻松地编写出高质量、可读性高的 RESTful API 文档，以及在 API 文档的自动生成和展示方面获益。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64ffccbc95b1f8cacde166e8