Swagger 是一个流行的 API 开发工具，可以让我们自动生成 API 文档、构建可扩展的 API，并为 API 提供交互式客户端。在前端开发中，我们经常需要与后端的 RESTful API 进行交互，这时使用 Swagger 自动生成 API 文档可以让我们更准确地了解接口的设计、使用方式等信息，提高前后端开发的协作效率。
安装 Swagger
首先，我们需要安装 Swagger。使用 npm 可以轻松安装 Swagger：
npm install -g swagger
安装完成后，我们可以使用 swagger --version 命令来检查是否已经安装成功。
创建 Swagger 规范文件
创建 Swagger 规范文件可以使用目前流行的两种格式：YAML 或 JSON。在本示例中，我们将采用 YAML 的格式。创建一个 swagger.yaml 文件，并写入以下内容：
-- -------------------- ---- -------
-------- -----
-----
------ --- --
------------ -- ------- ----- ------- --- --
-------- -------
--------- -------
--------
- -----
---------
- ----------------
---------
- ----------------
------
-------
----
-------- ------
------------ --------
---------
- ----------------
----------
----
------------ ----
------------
----
-------- --------
------------ -----------
---------
- ----------------
-----------
- ----- --
--- ----
------------ -- --
--------- ----
----- ------
----------
----
------------ ----在上述内容中，我们定义了 API 的基础信息和两个路由的定义。可以根据自己的需求添加更多的路由定义。
生成 API 文档
在我们创建了 Swagger 规范文件后，我们可以使用 Swagger 工具生成 API 文档。我们可以使用以下命令：
swagger generate spec -o ./swagger.json --yaml ./swagger.yaml
这个命令将读取 swagger.yaml 文件，生成相应的 JSON 格式的 API 文档。生成的文档将保存在 swagger.json 文件中。我们可以在其中查看自动生成的 API 文档。
另外，Swagger 还有一个图形化的交互式 UI，可以让我们更方便地浏览和测试 API。我们可以使用以下命令来启动 Swagger UI：
swagger serve -F swagger swagger.yaml
这个命令将启动 Swagger UI，并在浏览器中打开一个页面。在该页面中，我们可以看到自动生成的 API 文档，以及使用界面操作和测试 API。
使用 Swagger 生成客户端代码
对于前端开发者，Swagger 还提供了一个非常有用的功能：自动生成客户端代码。我们可以使用 Swagger 提供的代码生成器，根据 API 定义生成相应的客户端代码。我们可以通过以下步骤来实现：
安装 Swagger Codegen 工具：
npm install -g swagger-codegen
下载 Swagger 的代码生成器模板：
swagger-codegen init -i ./swagger.json -o ./my-app -l javascript
这将把下载的模板代码放入
./my-app目录。在
./my-app目录中，我们可以找到自动生成的客户端代码，可以直接在前端应用中使用。
除了 JavaScript 之外，Swagger 还支持许多其他语言的代码生成器，可以根据开发者的需要进行选择。
总结
使用 Swagger 自动生成 RESTful API 文档不仅可以方便开发者了解和使用 API，同时可以提高前后端协作的效率。在本文中我们介绍了如何使用 YAML 格式的 Swagger 规范文件，如何生成 API 文档、启动 Swagger UI、以及如何使用 Swagger Codegen 工具生成客户端代码。希望本文能为前端开发者提供一些借鉴和帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6471718b968c7c53b0f4f605