RESTful API 是一种基于 HTTP 协议的 Web API 设计风格，已经成为了现代 Web 应用程序的标准。Swagger 和 OpenAPI 是两个流行的 API 规范，它们可以帮助开发人员更好地设计和文档化 RESTful API。在本文中，我们将探讨 Swagger 和 OpenAPI 的实践，以及如何使用它们来提高 RESTful API 的开发效率。
Swagger 介绍
Swagger 是一个用于设计、构建、文档化和测试 RESTful API 的开源工具集。它包括一个 API 规范和一个用于生成文档和客户端 SDK 的工具。Swagger 规范是用 YAML 或 JSON 格式编写的，描述了 RESTful API 的请求和响应结构、参数、错误码等信息。Swagger UI 是一个用于展示 Swagger 规范文档的交互式界面，可以让开发人员更方便地测试和调试 API。
Swagger 实践
安装 Swagger
在 Node.js 中，可以使用 swagger-jsdoc 和 swagger-ui-express 两个模块来实现 Swagger 的功能。swagger-jsdoc 可以将 Swagger 规范注释写在代码中，然后生成 Swagger 规范文档。swagger-ui-express 可以将 Swagger 规范文档展示在一个 Web 界面中。
首先，我们需要安装这两个模块：
npm install swagger-jsdoc swagger-ui-express
创建 Swagger 规范
我们可以使用注释的方式来编写 Swagger 规范。下面是一个简单的例子：
-- -------------------- ---- ------- --- - -------- - ------- - ---- - -------- --- - -------- ------- - ---------- - ---- - ------------ -- - -------- - ----------- - ------- - ----- ------ -- ----------------- ----- ---- -- - ---------------- -------- --
在注释中，我们使用 @swagger 标签来指定这个 API 的 Swagger 规范。在 @swagger 标签后面，我们可以使用 YAML 或 JSON 格式来编写规范的定义。上面的例子中，我们定义了一个 GET 请求 /hello，返回一个字符串类型的响应。这个 API 的 Swagger 规范可以通过 swagger-jsdoc 来生成。
-- -------------------- ---- -------
----- ------------ - ------------------------
----- ------- - -
----------- -
-------- --------
----- -
------ --- -----
-------- --------
------------ -- ------ --- --- --------
-
--
----- ------------
-
----- ----------- - ---------------------在上面的代码中，我们创建了一个 Swagger 规范对象 swaggerSpec，其中包含了我们的 API 的基本信息，比如标题、版本、描述等。我们还指定了要扫描的 API 文件路径，这里是 ./app.js。swaggerSpec 对象可以传递给 swagger-ui-express 模块来展示 Swagger 规范文档。
展示 Swagger 规范
我们可以使用 swagger-ui-express 模块来展示 Swagger 规范文档。首先，需要将 Swagger 规范对象传递给 swaggerUi.setup 函数，然后将 swaggerUi.serve 函数添加到路由中。这里是一个简单的例子：
const swaggerUi = require('swagger-ui-express')
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))在上面的代码中，我们将 Swagger 规范文档展示在 /api-docs 路由上。当我们访问这个路由时，就可以看到 Swagger UI 界面，其中包含了我们的 API 的所有信息。
OpenAPI 介绍
OpenAPI 是一个基于 Swagger 规范的标准化 API 规范。它是由 OpenAPI Initiative 组织维护的，旨在提供一个开放的、可重用的、可扩展的 API 规范。OpenAPI 规范支持 JSON 和 YAML 两种格式，定义了 RESTful API 的请求和响应结构、参数、错误码、认证等信息。
OpenAPI 实践
安装 OpenAPI
在 Node.js 中，可以使用 express-openapi-validator 模块来实现 OpenAPI 的功能。它可以根据 OpenAPI 规范验证请求和响应，并报告任何错误。
首先，我们需要安装这个模块：
npm install express-openapi-validator
创建 OpenAPI 规范
我们可以使用 YAML 或 JSON 格式来编写 OpenAPI 规范。下面是一个简单的例子：
-- -------------------- ---- -------
-------- -----
-----
------ -- ---
-------- -----
------
-------
----
-------- --- - -------- -------
----------
------
------------ --
--------
-----------
-------
----- ------在上面的 YAML 文件中，我们定义了一个 GET 请求 /hello，返回一个字符串类型的响应。这个 YAML 文件可以作为我们的 API 的 OpenAPI 规范。
验证 OpenAPI 规范
我们可以使用 express-openapi-validator 模块来验证请求和响应是否符合 OpenAPI 规范。首先，需要创建一个 OpenAPI 规范对象，然后将它传递给 express-openapi-validator 中间件。这里是一个简单的例子：
const { OpenApiValidator } = require('express-openapi-validator')
const openApiValidator = new OpenApiValidator({
apiSpec: './openapi.yaml'
})
app.use(openApiValidator.validate())在上面的代码中，我们创建了一个 OpenApiValidator 对象，并指定了要验证的 OpenAPI 规范文件路径。然后，我们将 openApiValidator.validate() 中间件添加到路由中。这样，当有请求到达时，express-openapi-validator 就会验证请求和响应是否符合规范，并返回任何错误。
总结
Swagger 和 OpenAPI 是两个流行的 API 规范，它们可以帮助开发人员更好地设计和文档化 RESTful API。在本文中，我们探讨了 Swagger 和 OpenAPI 的实践，以及如何使用它们来提高 RESTful API 的开发效率。我们可以使用 swagger-jsdoc 和 swagger-ui-express 模块来实现 Swagger 的功能，使用 express-openapi-validator 模块来实现 OpenAPI 的功能。通过使用 Swagger 和 OpenAPI，我们可以更好地管理和维护我们的 RESTful API，提高开发效率和代码质量。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65e52d211886fbafa40e5efa