什么是 Swagger
Swagger 是一种用于描述和记录 RESTful API 的框架和规范，具有自动生成 API 文档的功能。开发RESTful API 时，我们可以使用 Swagger 规范来描述我们的 API，然后使用 Swagger 工具生成可读的 API 文档。
Swagger的优点：
- 自动生成文档，可以根据文档了解API接口的调用方式。
- 集成了多种模式的请求方式。
- 方便接口调试。
RESTful API 格式
在使用 Swagger 自动生成 API 文档之前，需要先了解 RESTful API 的格式。
RESTful API 是一种 Web API，它遵循 REST 架构风格。主要包括以下几个要素：
- 资源：我们需要操作的数据实体。
- 方法：对资源进行的操作，如 GET、POST、PUT 和 DELETE。
- URI：资源的地址，通过 URI 定位资源。
- 层级关系：在 URI 中传递参数的方式。
一个 RESTful API 的格式通常如下：
HTTP METHOD /resource URI [Request Body] Response Body
例如：
GET /users/2
{
"id": 2,
"name": "john",
"email": "john@example.com"
}Swagger 文档格式
Swagger 工具可以根据以下几个要素来生成 API 文档：
- Path：相对路径，它说明了 API 接口的 URL 和请求方式。
- Operation ID：操作的唯一 ID，它们用于链接 Swagger 描述和实现代码。
- Response 200：API 的成功响应。
- Consumes 和 Produces：请求和响应的 MIME 类型。
一个 Swagger 文档的例子如下：
-- -------------------- ---- -------
-------- -----
-----
-------- -----
------ ------- ------ ---
------------ - ------ --- ---- ---- - -------- -- -- --------
----- -------------------
--------- ---
--------
- ----
- -----
------
-----
-----
-----
- ---
-------- --- - --- --- -- --- -----
------------ ------
---------
- ----------------
---------
- ----------------
-----------
- --- ----
----- ----
------------ --- ------ ---- ----- -- -- ----- -- --- -----
--------- ----
-------
----- -------------------
----------
----
------------ ------- -----
---------
- --------------
- ----------
- ---------
------------
----
----- ------
---------
- ----
-----------
---
----- -------
------- -----
-----
----- ------
----
----- ------如何使用 Swagger 自动生成 API 文档
我们可以使用 Swagger 相关的库、插件或框架来生成 Swagger 文档。这里介绍使用 Node.js 的 Express 和 swagger-ui-express 库来生成 Swagger 文档。
示例代码
安装库
npm install --save express swagger-ui-express
引入库
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');定义 Swagger 相关信息
-- -------------------- ---- -------
----- ----------------- - -
----- -
------ -------- ------- -- --- --
-------- -------- -- --- ---
------------ -------- --- ---- -- --- --
--
----- ----------------- -- --- --
--------- ---- -- --- --
--
----- ------- - -
------------------
----- ------------------ -- ----- --- --
--生成 Swagger 文档
const swaggerSpec = swaggerJSDoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));实现 API 接口
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ------ - ----------------- --- - -------- - ------- - ---- - ----- - - ---- - ------------ --- --- ----- - --------- - - ---------------- - ---------- - ---- - ------------ -- ----- -- ----- - ------- - ----- ------------------------ -- -------------------- ----- ---- -- - -- ---- ---
客户端通过 Swagger UI 查看 API 文档
当 API 服务器启动后，在浏览器中打开 localhost:3000/api-docs，即可查看生成的 API 文档。
总结
本文主要介绍了使用 Swagger 自动生成 API 文档的方法，并提供了 Node.js 的示例代码。Swagger 自动生成 API 文档可以提高开发效率、代码查错效率，同时也方便了 API 调用人员的接口测试和安全控制。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64fc3898f6b2d6eab3213cf2