Swagger 是一种 API 描述语言，它可以帮助我们更加方便地编写和维护 API 文档。Swagger-tools 则是 Swagger 的一个 npm 包，提供了各种 API 构建和管理工具，它可以帮助我们快速构建出标准的 RESTful API。
下面我们来详细了解一下如何使用 swagger-tools。
安装
安装 Swagger-tools 只需要一个简单的命令即可：
npm install -g swagger-tools
运行
Swagger-tools 可以通过命令行工具来启动：
swagger project start
我们需要提供 YAML 或 JSON 格式的 Swagger 文件，Swagger-tools 会自动根据文件里的描述信息生成出对应的 API。
配置
Swagger-tools 的配置需要在 swagger-tools.yaml 文件中进行，这个文件需要和 Swagger 文件在同一目录下。
一个最基础的 swagger-tools.yaml 文件配置如下：
# Swagger文件路径 swagger: './swagger.yaml' # 运行相关信息 appRoot: ./
其中 swagger 指明了 Swagger 文件的路径，appRoot 则是应用的根目录。
除此之外，swagger-tools.yaml 文件还可以配置各种中间件，例如 swagger-security、swagger-express-middleware、swagger-router 等。这些中间件可以绑定到指定的路由上，以实现各种定制化的功能。
示例
最后我们来演示一个简单的 Swagger 文件和它所对应的 API。
-- -------------------- ---- -------
-------- -----
-----
-------- -------
------ --- ----
- ---- - -------- ------- --- -----
----- ----------------
--------- ------
--------
- -----
- ----
- ----------
------
------
----
-------- -------- --- -----
----------
------
------------ -- ---- -- -----
-------
----- -------
------
----- -------------------
----------
-----
-------- ---- - --- ----
-----------
- --- ------
----- -----
------------ ---- --- -- ----
--------- ----
-------
----- -------------------
----------
------
------------ ---- ----- ----
-------
----- -------------------
------------
----
----- --------
---------
- ----
-----------
-----
----- --------
----
----- ---------上述示例文件定义了一个名为 My API 的 API，它可以列出和添加宠物信息。
启动 API：
swagger project start
访问 API：
GET http://localhost:5000/api/pets POST http://localhost:5000/api/pets/add
当我们发出 GET 请求时，API 会返回所有宠物的信息：
-- -------------------- ---- -------
-
-
------- ------
------ -
--
-
------- --------
------ -
-
-当我们发出 POST 请求时，API 会添加一只新宠物：
{
"name": "Lucy",
"age": 3
}至此，我们已经成功构建了一个简单的 API，并使用 Swagger-tools 快速生成了对应的 API 描述文件。
总结
Swagger-tools 是一款便捷易用、功能强大的 npm 包。通过它，我们可以快速构建出标准的 RESTful API，并自动生成 API 的描述信息，大大提高了 API 文档编写的效率和质量。希望这篇教程能够帮助你入门并掌握 Swagger-tools 的使用。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedab61b5cbfe1ea0610764