什么是 Swagger
Swagger 是一个 RESTful API 的工具集，它包含了众多的工具，能够帮助我们构建和测试 Web API，同时也可以帮助我们进行 API 文档的管理和发布。
Swagger 主要由三部分组成：
- Swagger Editor：用于编辑 swagger.yml 文件的在线工具，该文件用于描述 RESTful API。
- Swagger UI：用于展示 RESTful API 文档的页面，包括 API 端点、请求和响应信息等。
- Swagger Codegen：可用于生成客户端和服务器端的代码。
安装 Swagger
安装 Swagger 很简单，只需要使用 NPM 安装即可，执行以下命令即可安装：
npm install -g swagger
使用 Swagger 构建和测试 RESTful API
创建 Swagger 项目
使用 Swagger 构建 RESTful API 首先需要创建一个项目，执行以下命令来创建项目：
swagger project create myproject
创建完成后，会生成以下文件：
-- -------------------- ---- -------
---------
--- ---
- --- -------
- --- ------------
--- ------
--- ------
- --- ------------
--- ------------
--- ---------
--- ----
--- ---
--- ---------其中，api/swagger/swagger.yaml 文件用于描述该项目的 RESTful API。
编写 Swagger 文件
在 Swagger 文件中我们需要定义 API 的细节，如 API 端点、参数、请求和响应等信息。
以下是一份 Swagger 文件的示例，该文件描述了一个简单的 API，用于获取一些数据：
-- -------------------- ---- -------
-------- -----
-----
------ ---- ---
------------ --- --- ------- ---- ----
-------- -----
--------- ---
--------
- ----
------
------
----
-------- --- ---- ----
------------ --- ---- --- -- --- ---- ----
-----------
- ----- --
--- -----
------------ --- -- -- ----
--------- ----
----- ------
----------
----
------------ --
-------
----- ------
-----------
-----
----- ------启动 API 服务器
在编写完 Swagger 文件后，我们需要让 Swagger 项目运行起来，以便能够测试我们的 API，使用以下命令启动 API 服务器：
swagger project start
该命令会将 API 服务器启动在 3000 端口上。
测试 API
在 API 服务器启动后，我们可以使用 Swagger UI 来测试我们的 API，只需要在浏览器中输入以下 URL 即可访问：
此时，我们就可以在 Swagger UI 中测试我们的 API 了。
生成客户端代码
Swagger 不仅可以帮助我们构建和测试 API，还能够生成客户端的代码，以便我们在客户端调用 API 时更加便捷。
使用以下命令即可生成客户端代码：
swagger-codegen generate -i api/swagger/swagger.yaml -l javascript -o client
该命令将会根据我们编写的 Swagger 文件来生成 JavaScript 的客户端代码，并保存在 client 目录下。
总结
使用 Swagger 构建和测试 RESTful API 非常简单，只需要按照上述步骤进行操作即可。使用 Swagger 不仅能够提高 API 开发的效率，而且能够帮助我们更好地管理和维护 API。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64f0686ef6b2d6eab3a70618