在前端开发中，我们经常需要与后端进行交互，而 RESTful API 是目前最常用的一种方式之一。在与后端进行开发过程中，一个我们必须要面对的问题就是 API 文档的编写和更新，这对于我们来说是一件繁琐且易出错的事情。而 Swagger 就提供了一种方便快捷的方式来自动生成 RESTful API 文档，极大地减少了我们的开发成本。
什么是 Swagger？
Swagger 是一个开源的 API 文档生成工具，它支持 RESTful API 规范，可以自动生成高质量的 API 文档。Swagger 主要支持 YAML 或 JSON 格式的 API 文档描述文件，通过各种工具可以把这些描述文件转成丰富的 API 文档，可以包括 API 的参数、请求方式、响应信息、错误码等内容。
Swagger 的优点
- 自动生成文档：通过 Swagger，能够自动生成 API 文档，减少了手写文档的步骤，减少出错的可能性；
- 规范接口：通过定义接口规范和文档，使得接口规范和文档能够进行统一管理，方便日后维护；
- 调试接口：Swagger 提供了测试接口的功能，可以使接口在调试时更容易理解；
- 接口可视化：Swagger 提供了友好的界面，使得接口信息可以通过可视化界面进行查看。
如何使用 Swagger 自动生成 RESTful API 文档？
下面让我们来一步步探讨如何使用 Swagger 自动生成 RESTful API 文档。
安装 Swagger
在使用 Swagger 之前，我们需要先安装它。Swagger 的安装非常简单，只需要运行以下指令即可：
--- ------- -- -------
编写 Swagger 描述文件
接下来，需要编写一个描述文件，该文件是 Swagger 自动生成 RESTful API 文档的依据。在描述文件中，我们需要指定 API 的基本信息、请求参数和响应等信息。
例如，我们有一个简单的 API，用于获取用户信息。我们可以使用以下描述文件来描述它：
-------- -----
-----
------ ---- ---
-------- -----
------------ --- --- ---- ----------
--------- -------
------
-----------
----
-------- --- ---- -- --
------------ -------- --- ---- ------ ----- -- ---- --
------------ -----------
---------
- ----------------
-----------
- ----- --
--- ----
------------ -- -- --- ---- -- -----
--------- ----
----- -------
----------
----
------------ ---- ------
-------
----- --------------------
----
------------ ---- --- -----
------------
-----
----- ------
-----------
---
----- ------
-----
----- ------
----
----- -------
-------
----- ------在上面的描述文件中，我们定义了一个 GET 请求，路径是 /user/{id}，返回的结果是一个 User 对象。具体的解释可以参考注释。
生成 API 文档
我们已经编写好了描述文件，接下来就可以生成 API 文档了。使用 Swagger，我们可以使用命令行或 Web 界面两种方式。
命令行生成 API 文档
使用 Swagger 生成 API 文档非常简单，只需要执行以下命令即可：
------- -------- ---- -- ------------ -- -------------
其中，<input-file> 是我们编写的 Swagger 描述文件，可以是 json 或 yaml 格式；<output-file> 是生成的 API 文档的存储路径和文件名。
例如，我们可以使用以下命令来生成 API 文档：
------- -------- ---- -- ------------- -- -------------
这将把 user-api.yaml 描述文件转换成 user-api.json API 文档。
Web 界面生成 API 文档
Swagger 还提供了一个 Web 界面，可以让我们更方便地生成 API 文档。只需要访问以下网址即可：
------------------------------
在 Web 界面中，我们需要输入 API 的基本信息，然后通过可视化的方式来输入请求参数、响应等信息，最终生成的 API 文档可以直接在文档中进行查看。
查看 API 文档
生成 API 文档之后，我们就可以来查看它，确认生成的文档是否符合我们的预期。除了使用 Swagger 提供的 Web 界面进行查看之外，我们还可以使用 Swagger UI 工具来展示 API 文档。
在使用 Swagger UI 展示 API 文档之前，我们需要先安装它。只需要执行以下命令即可：
--- ------- ----------
安装完成后，我们需要在 HTML 文件中添加以下代码：
--------- -----
------
------
-------------- ----------
----- ---------------- --------------- -------------------------- -
-------
------
---- ----------------------
------- -----------------------------------------
------- ----------------------------------------------------
--------
------------- - ---------- -
--- -- - -----------------
---- ----------------
------- --------------
------------ -----
-------- -
-----------------------------
-------------------------
--
-------- -
-----------------------------------
--
------- ------------------
--
-
---------
-------
-------其中，url 属性是我们已经生成的 API 文档路径，需要注意路径的正确性。
当我们在浏览器中打开这个 HTML 文件时，就可以看到一个完整的 API 文档，包括接口信息、请求参数和响应等内容。
总结
在本文中，我们学习了 Swagger 描述文件的编写方法、Swagger 工具的使用方法以及如何使用 Swagger UI 展示 API 文档。通过使用 Swagger，我们可以方便快捷地生成高质量的 RESTful API 文档，减少了手动编写文档的步骤，提高了我们的开发效率。同时，Swagger 还可以规范我们的接口规范和文档，易于管理和后期维护。
来源：JavaScript中文网 ，转载请联系管理员！ 本文地址：https://www.javascriptcn.com/post/653e5b197d4982a6eb7dee1a