背景介绍
在 Web 开发中，RESTful API 是一个非常重要的概念。它是一种使用 HTTP 协议来操作 Web 资源的接口风格。而 Swagger 和 OpenAPI 规范则是为了解决 RESTful API 文档编写、测试等问题的一套标准和工具。
什么是 Swagger？
Swagger 是一种 RESTful API 文档编写和测试的框架。它可以通过描述符文件自动生成 API 文档，并提供了一些基本的测试工具。Swagger 的描述符文件是一份 JSON 或者 YAML 格式的文件，用来描述整个 API 的信息，包括 API 的请求方法、参数、返回值等。
什么是 OpenAPI？
OpenAPI 规范是 Swagger 的升级版，也是一套 RESTful API 文档编写和测试的标准。与 Swagger 相比，OpenAPI 规范将描述符文件的格式扩展为 JSON 或 YAML，并且包含更多的功能和选项。
使用 Swagger-UI 显示 RESTful API 文档
Swagger-UI 是 Swagger 的一个子框架，他可以用来将 Swagger 或 OpenAPI 规范描述的 API 文档在 Web 页面中显示出来。用户可以通过 Swagger-UI 显示的文档了解 API 的基本信息和使用方式，也可以通过 Swagger-UI 提供的测试工具进行测试和调试。
下面是一个使用 Swagger-UI 可以显示的 RESTful API 文档的示例：
-- -------------------- ---- -------
-----------
----
-------- ---- - ---- -- ---
------------ -------------
---------
- ------------------
-----------
- ----- ----
--- ------
------------ ---- -- -- --- ---- -- ---------
--------- ----
----- ---------
------- -------
----------
----
------------ ----------- ----------
-------
----- --------------------
----
------------ -------- -- ---------
----
------------ ----- --- ------
---------
- -------- --使用示例
下面我们将通过一个简单的示例来说明如何使用 Swagger 和 OpenAPI 规范。假设我们有一个 Web 应用程序，需要提供一个 RESTful API 来查询一组数据集中的数据。我们可以按照以下步骤实现：
- 首先，我们需要编写一个 OpenAPI 规范描述文件，文件中需要包含 API 的基本信息、请求方法、参数和返回值等。我们可以使用 YAML 或 JSON 等格式来编写描述文件。示例描述文件如下：
-- -------------------- ---- -------
-------- -----
-----
------ ----- ----
-------- -------
------------ -- ------ ------- --- -- ----- ------
----- -------------
--------- ---------
--------
- -------
---------
- ------------------
---------
- ------------------
------
------
----
-------- ---- -----
------------ ---- --- ---- ---- --- ---------
-----------
- ----- ---------
--- -------
------------ ---- ---- -- --- ------- -- -------
--------- ----
----- --------
- ----- -------
--- -------
------------ ---- ----- ------ -- -----
--------- ----
----- --------
----------
----
------------ ----------- ---------
-------
----- --------------------
----
------------ -------- --------
----
------------ --------------
----
------------ ----- --- ------
----
------------ --------- ------ ------
------------
-----
----- --------
-----------
-----
----- --------
------
----- --------编写完成 OpenAPI 规范描述文件后，我们可以使用 OpenAPI 工具自动生成 API 文档和测试工具。具体步骤如下：
- 安装 Node.js
- 使用 npm 安装 OpenAPI-CLI 工具：
npm install -g openapi-cli - 使用 OpenAPI-CLI 工具生成 API 文档：
oas3 api_spec.yaml --output=./public/openapi.json - 在 Web 应用程序中安装 Swagger-UI 模块：
npm install swagger-ui-express - 在 Web 应用程序中配置 Swagger-UI 的路由和选项：
const swaggerUi = require('swagger-ui-express'); const swaggerDocument = require('./public/openapi.json'); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
配置完成后，我们可以在浏览器中访问
http://example.com/api-docs查看 API 文档，并使用 Swagger-UI 提供的测试工具进行测试和调试。
总结
Swagger 和 OpenAPI 规范是一套非常有用的 RESTful API 文档编写和测试的标准和工具。通过了解 Swagger 和 OpenAPI 规范，我们可以更加方便地编写 RESTful API 文档，并且可以使用 Swagger-UI 快速开发出功能强大、易于维护的 Web 应用程序。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64adc32548841e98949c7829