什么是 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 的格式通常如下：
---- ------ --------- --- -------- ----- -------- ----
例如：
--- -------- - ----- -- ------- ------- -------- ------------------ -
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
引入库
----- ------- - ------------------- ----- --------- - ------------------------------ ----- ------------ - -------------------------
定义 Swagger 相关信息
----- ----------------- - -
----- -
------ -------- ------- -- --- --
-------- -------- -- --- ---
------------ -------- --- ---- -- --- --
--
----- ----------------- -- --- --
--------- ---- -- --- --
--
----- ------- - -
------------------
----- ------------------ -- ----- --- --
--生成 Swagger 文档
----- ----------- - ---------------------- -------------------- ---------------- ------------------------------
实现 API 接口
----- ------- - ------------------- ----- ------ - ----------------- --- - -------- - ------- - ---- - ----- - - ---- - ------------ --- --- ----- - --------- - - ---------------- - ---------- - ---- - ------------ -- ----- -- ----- - ------- - ----- ------------------------ -- -------------------- ----- ---- -- - -- ---- ---
客户端通过 Swagger UI 查看 API 文档
当 API 服务器启动后，在浏览器中打开 localhost:3000/api-docs，即可查看生成的 API 文档。
总结
本文主要介绍了使用 Swagger 自动生成 API 文档的方法，并提供了 Node.js 的示例代码。Swagger 自动生成 API 文档可以提高开发效率、代码查错效率，同时也方便了 API 调用人员的接口测试和安全控制。
来源：JavaScript中文网 ，转载请联系管理员！ 本文地址：https://www.javascriptcn.com/post/64fc3898f6b2d6eab3213cf2