在软件开发中，RESTful API 已经成为了一种常见的 Web API 形式。为了方便开发者使用 API，构建一份详细的 API 文档显得尤为重要。Swagger 是一款流行的 RESTful API 文档工具，本文将会介绍如何通过 Swagger 来构建 RESTful API 文档。
什么是 Swagger?
Swagger 是一款 RESTful API 的可视化文档，与后端代码相对应。它使用 OpenAPI 规范来描述和定义 RESTful API 的结构，使得 API 的使用更加自然合理，更重要的是，能够让前端及其他非后端开发者快速理解 API 的参数以及返回值结构。
Swagger 最初是由 Tony Tam 在 2012 年创建的，从 2014 年开始由 SmartBear Software 开发与维护。Swagger 的核心组件包括：
- Swagger Editor：可视化编辑器，可用于创建、编辑并验证 Swagger 规范。
- Swagger UI：交互式 API 文档，可让开发者直接测试并查看 API。
- Swagger Codegen：根据 Swagger 规范快速生成各种语言的客户端和服务端代码。
Swagger 已经逐渐成为了最受欢迎的 RESTful API 文档工具之一，并且是大多数 RESTful API 团队的首选之一。
如何使用 Swagger?
Swagger 规范有三个版本：Swagger 1.0、Swagger 2.0 和 OpenAPI 3.0。目前 Swagger 2.0 和 OpenAPI 3.0 是最流行的版本，并已成为行业标准。以下是一些步骤，让你快速构建一个 RESTful API 的文档：
第一步：安装 Swagger
使用 Swagger 需要在本地安装 Node.js 环境和 Swagger 依赖，请执行以下命令：
npm install -g swagger
第二步：创建 Swagger 工作目录
通过执行以下命令，在项目目录下创建 Swagger 工作目录：
swagger project create <project_name>
执行完毕，会自动生成一个 Swagger 工程的目录结构：
-- -------------------- ---- -------
-------
------------
----------
---------------
---
----
--------
------------
--- - config：Swagger 工程的配置文件夹
- api：工程中实现的所有 API 服务的 API 定义目录
第三步：使用 Swagger 编辑器编辑 API 创建必要文件
Swagger 中使用文件保存 API，因为文件内容可以描述 API 的信息和结构，使其更易于管理。以下是一些必要的文件以及每个文件的作用：
/api/swagger/swagger.yaml：描述 RESTful API 结构，并存放文档结构定义和类型。 /config/default.yaml：配置文件，包含应用程序的通用和特殊配置。
当完成以上三个步骤后，就可以开始编辑 Swagger API 了。
示例代码
这里提供了一个完整的 Swagger API.yaml 文件示例，该文件描述了一个简单的 RESTful API：
-- -------------------- ---- -------
-------- -----
-----
------------ --------------
-------- -------
------ -------
----- -----------
--------- ------
--------
- ------
---------
- ------------------
---------
- ------------------
------
------
----
-----
- ----
------------ ----------
------------ --------
----------
----
------------ ----------
-------
----- -------
------
----- --------------------
------------
-----
----- --------
---------
- ----
- ------
-----------
---
----- ---------
------- -------
-----
----- --------
---
-- --
------- ----------- ------- --- --------------- ------- ------ ------- --- ------- --- -------------------- ------- -------------- ------- ------------------ ------- --- ---
- ------------------------------------------------------------------------------ --------
------------------------------------------------------------------------------------------------------------------------