随着 RESTful API 的广泛应用，对于开发者来说，编写 RESTful API 文档已经成为一项必要的工作。然而，手动编写文档不仅费时费力，而且容易因疏忽而出现错误。有了 Swagger 工具，开发者可以自动化生成 RESTful API 文档，并且可以方便地查看和测试 API。
什么是 Swagger？
Swagger 是一组开源工具和规范，其中包括 OpenAPI 规范、Swagger UI 和 Swagger Editor 等。OpenAPI 规范定义了如何描述 RESTful API 的元数据，而 Swagger UI 和 Swagger Editor 则可以根据该元数据生成 API 文档和测试工具。
为什么使用 Swagger？
使用 Swagger 可以获得以下好处：
提高开发效率。 使用 Swagger 可以自动生成文档，节省手动编写文档的工作量。此外，Swagger 的交互式 UI 和测试工具可以帮助开发者更快地理解 API 的使用方式。
提高 API 的可靠性和稳定性。 Swagger 可以在开发期间发现 API 的潜在问题，并使 API 更易于维护。此外，Swagger 还支持自动生成客户端 SDK，可以减少客户端和服务端之间的通信问题。
提高 API 的可扩展性。 自动生成的文档和 SDK 可以帮助新开发人员更快地上手，并提供足够的信息，以便其他开发人员更快地扩展 API 功能。
如何使用 Swagger？
Swagger 的使用分为两步：定义 OpenAPI 规范和生成文档。
1. 定义 OpenAPI 规范
OpenAPI 规范是一种描述 RESTful API 的元数据格式。使用 JSON 或 YAML 格式定义 OpenAPI 规范，可以使用 Swagger 编辑器编辑，也可以手动编写。
以下是一个使用 YAML 格式定义的 OpenAPI 规范示例：
-- -------------------- ---- -------
-------- -------
-----
------ ----- ----
-------- -------
------------ -- ------ --- -- ------ ------
------
-------
----
-------- --------- --- ------
----------
----
------------ ------------
-----
-------- ------- - --- -----
------------
--------
-----------------
-------
----- ---------------------------
--------- ----
----------
----
------------ ------------
------------
----
-------- --------- - ---- -- ---
-----------
- ----- ----
--- ------
--------- ----
-------
----- ---------
----------
----
------------ ------------
-----------
--------
-----
----- --------
-----------
---
----- ---------
------
----- --------
----------
----- ---------上述示例使用 YAML 格式描述了一个 Todo API，包含获取全部 todo、创建 todo 和根据 ID 获取指定 todo 的三个操作。其中，每个操作包含一个或多个参数、一个或多个响应和一个或多个请求体，可以通过该规范自动生成文档和交互式界面。
2. 生成文档
生成文档需要使用 Swagger UI 或常见的后端 Web 框架。Swagger UI 是一款以 HTML、CSS 和 JavaScript 实现的交互式文档生成器，可以直接将 OpenAPI 规范作为输入，在浏览器中查看 API 文档。Swagger UI 还提供了测试 API 的功能，可以快速测试 API 的响应。
下面是如何使用 Swagger UI 生成 API 文档的示例：
-- -------------------- ---- -------
--------- -----
------
------
----- ----------------
----------- --- ---------------------
----- ---------------- --------------- -------------------------------------------------------------------------------
-------
------
---- ----------------------
------- --------------------------------------------------------------------------------------------
------- -------------------------------------------------------------------------------------------------------
--------
------------- - ---------- -
----- -- - -----------------
---- ------------ -- - --- --- --- ----------
------- --------------
-------- -
-----------------------------
-------------------------
--
------- ------------------
---
-
---------
-------
-------使用 Swagger UI 生成的 API 文档界面如下所示：
总结
Swagger 为开发者提供了自动生成 RESTful API 文档的方便工具，可以降低编写文档的工作量、提高 API 的可靠性和稳定性，以及提高 API 的可扩展性。此外，Swagger 还提供了交互式界面和 SDK，方便开发人员进行测试和任务。在实际开发中，使用 Swagger 可以大大提高开发效率，减少因错误而带来的不必要麻烦。
示例代码
以下是一个使用 Node.js 和 Express 生成 Swagger API 的示例：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- --------- - ------------------------------ ----- ---- - ------------------ ----- --------------- - ---------------------------- ----- --- - ---------- -------------------- ---------------- ---------------------------------- -- ----------- ----------------- ----------------- ----- ---- -- - -- --- --- ----- --- ------------------ ----- ---- -- - -- ------ - --- ---- --- --------------------- ----- ---- -- - -- --- - ---- -- -- --- ---------------- -- -- ----------------- --- --------- -- ---- ---------
swagger.yaml 文件内容如下：
-- -------------------- ---- -------
-------- -------
-----
------ ----- ----
-------- -------
------------ -- ------ --- -- ------ ------
------
-------
----
-------- --------- --- ------
----------
----
------------ ------------
-----
-------- ------- - --- -----
------------
--------
-----------------
-------
----- ---------------------------
--------- ----
----------
----
------------ ------------
------------
----
-------- --------- - ---- -- ---
-----------
- ----- ----
--- ------
--------- ----
-------
----- ---------
----------
----
------------ ------------
-----------
--------
-----
----- --------
-----------
---
----- ---------
------
----- --------
----------
----- ---------在命令行中运行以下命令即可启动应用：
node app.js
在浏览器中访问 http://localhost:3000/api-docs，即可查看生成的 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/647950fd968c7c53b0557f12