RESTful API 是一种常见的 API 设计风格，它基于 HTTP 协议，以资源为核心，通过 HTTP 方法进行操作，使得 API 的设计更加简洁、易于扩展和维护。而 Swagger UI 则是一种开源的 API 文档工具，可以帮助我们更好地描述和展示 RESTful API 的接口、参数、响应、请求样例等信息，方便开发、测试、文档的协作和管理。
在本文中，我们将讨论如何使用 Swagger UI 工具来文档化我们的 RESTful API。
1. 安装 Swagger UI
Swagger UI 是一个基于 HTML、CSS 和 JavaScript 技术的 Web App，它可以通过多种方式进行安装和使用。我们可以下载其稳定版本的源码，也可以使用 Node.js 和 Docker 等工具来部署和管理 Swagger UI，还可以直接使用外部的 Swagger Hub 平台进行在线文档化和协作。
在本文中，我们使用 Node.js 和 npm 工具进行安装和配置 Swagger UI。你需要先确保你已经安装好了 Node.js 和 npm，并能够正常运行它们。
在命令行中输入以下命令进行全局安装 Swagger UI：
npm install -g swagger-ui-express
这个命令会在全局环境中安装 Swagger UI 和其相关的依赖库和插件。安装完成后，我们可以使用它提供的命令来创建和启动我们的文档服务。
2. 创建 RESTful API
在开始使用 Swagger UI 之前，我们需要先编写我们的 RESTful API，以使我们的 API 能够被 Swagger UI 所读取和展示。
假设我们要创建一个简单的用户管理系统的 RESTful API，它包括以下几个接口：
- GET /users: 获取所有用户的信息
- GET /users/{id}: 获取用户 ID 为 {id} 的信息
- POST /users: 创建一个新用户
- PUT /users/{id}: 更新用户 ID 为 {id} 的信息
- DELETE /users/{id}: 删除用户 ID 为 {id} 的信息
我们可以使用 Node.js 和 Express 框架来实现这个 API 的基本框架。下面是一个简单的实现示例：
-- -------------------- ---- -------
----- ------- - -------------------
----- --- - ----------
----- ---------- - -----------------------
-- -- ---- - ---------- -----
---------------------------
------------------------------- --------- ----- ----
-- -------
--- ----- - -
- --- -- ----- -------- ------ ------------------- --
- --- -- ----- ------ ------ ----------------- --
- --- -- ----- ---------- ------ --------------------- --
--
-- --------
----------------- ----- ---- -- -
----------------------------
---
-- --------
--------------------- ----- ---- -- -
----- -- - ----------------------
----- ---- - ------------ -- ---- --- ----
-- ------ -
---------------------------
- ---- -
-----------------------
-
---
-- -------
------------------ ----- ---- -- -
----- ---- - ---------
-- ----- -- --------- -- ----------- -
------- - ------------ - --
-----------------
---------------------------
- ---- -
---------------------- -------- -------- ---- ----- ---
-
---
-- --------
--------------------- ----- ---- -- -
----- -- - ----------------------
----- ---- - ------------ -- ---- --- ----
-- ------ -
----- ------- - ---------
-- -------- -- ------------ -- -------------- -
--------- - -------------
---------- - --------------
---------------------------
- ---- -
---------------------- -------- -------- ---- ----- ---
-
- ---- -
-----------------------
-
---
-- --------
------------------------ ----- ---- -- -
----- -- - ----------------------
----- --------- - ----------------- -- ---- --- ----
-- ---------- -- -- -
----------------------- ---
-----------------------
- ---- -
-----------------------
-
---
-- ----
----- ---- - ---------------- -- -----
---------------- -- -- -
------------------- --------- -- ---- ----------
---这个示例中，我们定义了一个 Express 应用程序，并设置了一些基本的路由和中间件，来响应各种不同的 HTTP 请求（如 GET、POST、PUT、DELETE），以实现我们的 RESTful API。
我们可以先启动这个应用程序，通过访问 http://localhost:3000/users 这个地址，来测试我们的 GET /users 接口是否正常。可以看到在浏览器中返回了一段 JSON 数据，包括了所有的用户信息。
3. 集成 Swagger UI
Swagger UI 的文档展示和管理功能，可以通过多种方式进行集成和配置。我们可以通过环境变量、配置文件、端口号、访问认证等方式，对 Swagger UI 进行不同的配置和参数设置，以满足不同的需求和安全策略。
在本例中，我们采用一个最简单的方式来集成 Swagger UI，即通过 swagger-ui-express 和 swagger-jsdoc 这两个 Node.js 模块来快速生成文档和启动服务。它们可以处理我们的 API 代码文件，生成相应的 Swagger 规范（OpenAPI 规范），并将这些规范部署为一个独立的 Swagger UI 服务。
我们需要先安装这两个 Node.js 模块，可以使用以下命令：
npm install --save swagger-ui-express swagger-jsdoc
其中，swagger-ui-express 模块提供了 Swagger UI 的 Web 应用程序，在我们的 Express 框架中进行配置和启动。在下面的代码示例中，我们将其设置为 /api-docs 前缀，以便于访问和管理：
-- -------------------- ---- -------
----- --------- - ------------------------------
----- ------------ - -------------------------
-- ------------- -------------
----- -------------- - -
----------- -
-------- --------
----- -
------ ------- ---- ---------- -----
-------- --------
------------ -- ------ ------- --- --- -------- -------
--
-------- -
- ---- ----------------------- --
--
--
----- ----------------
--
-- ---------- -------------
----- ----------- - -----------------------------
-- ----- ------- --------
-------------------- ---------------- ------------------------------在上面的代码片段中，我们首先定义了 Swagger 的基本信息，包括 API 的名称、版本、描述信息等。我们也可以配置其他的元数据，如许可证、联系信息、扩展属性等。
我们还指定了我们的 Express 应用程序将从哪些 API 代码文件中收集文档信息。在本例中，仅收集了一个 server.js 文件的信息。
最后，我们使用 swagger-ui-express 模块中的中间件，将 Swagger UI 部署到我们的 Express 应用程序中，并设置了 /api-docs 这个访问前缀。这样，我们就可以通过访问 http://localhost:3000/api-docs 这个地址，来浏览和管理我们的 RESTful API 文档了。
4. 测试 Swagger UI
现在，我们已经完成了对 RESTful API 和 Swagger UI 的集成和配置工作。下面，我们来测试我们的 Swagger UI 是否能够正常工作，以及如何更好地使用它来文档化我们的 API。
我们首先启动我们的服务：
node server.js
然后，我们在浏览器中访问 http://localhost:3000/api-docs 这个地址，便可以看到 Swagger UI 的文档主页面了。
在文档主页面，我们可以看到我们的所有 API 接口的详细信息，包括路由，请求方法，参数，请求和响应示例等。我们还可以通过搜索框、标签页、分类、排序等方式，来快速浏览和筛选我们的 API 文档。
我们可以选择某个具体的 API 标签页来查看其更详细的信息。例如，我们选择 users 这个标签，便可以看到所有和用户有关的 API 接口信息。
对于每个 API 接口，我们可以看到它的名称、请求方法、请求 URL、参数、请求体、响应等信息。在右侧，还会显示该请求的 Curl、JavaScript、Python、Ruby、Java 等语言代码示例，方便不同语言的应用程序进行集成和调用。我们还可以在页面中直接进行请求，以测试和调试我们的 API 接口。
如果需要快速定位某个 API 接口，我们可以通过左侧的目录树或搜索框进行快速跳转。如果需要通过代码来调用 API，我们可以直接复制右侧的代码示例，并进行修改和调用。
另外，我们还可以通过链接到 Swagger UI 的 JSON 或 YAML 接口，来以机器可读的形式，直接获取和使用我们的 API 规范信息。
总结
通过上面的介绍，我们可以看到，Swagger UI 是一种非常强大、灵活和易于使用的工具，可以方便我们对 RESTful API 进行快速文档化和管理。无论是开发、测试、调试还是文档编写，都可以得到很好的支持和协作。
在实际使用中，我们还可以根据自己的需求和情况，对 Swagger UI 进行更精细的设置和扩展。例如，我们可以添加更多的元数据信息，支持多语言接口文档，进行访问认证和授权，实现多版本 API 管理，集成更多的持续集成和部署工具等等。
综合而言，Swagger UI 是一个不错的选择，可以帮助我们更好地编写、测试、管理和发布 RESTful API。让我们一起享受这个强大的工具，来提高我们的开发效率和代码质量吧！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6474032c968c7c53b0174db3