在现代的应用中，API（Application Programming Interface）已经成为不可或缺的一部分。关于如何正确地设计和文档化 API，是每个开发者必须掌握的技能。
Swagger 是一种流行的 API 设计和文档化工具，它提供了一套标准化的方式来描述 RESTful APIs。在本文中，我们将介绍如何使用 Swagger 构建 RESTful API 文档。
什么是 Swagger？
Swagger 是一种开源的 API 规范，允许开发者用简单的 JSON 或 YAML 格式描述他们的 RESTful API。在规范定义的基础上，Swagger 提供了一组工具来自动生成文档、生成客户端代码和执行测试。
Swagger 可以帮助开发者：
- 描述 API 的请求、响应和认证方式。
- 自动生成符合规范的 API 文档。
- 生成客户端 SDK。
- 提供交互式 API 测试界面。
如何使用 Swagger？
以下是使用 Swagger 构建 RESTful API 文档的步骤：
1. 安装 Swagger
npm install swagger-ui-express swagger-jsdoc
2. 创建 Swagger 规范文件
用 YAML 或 JSON 方式创建 Swagger 规范文件。下面是一个示例：
-- -------------------- ---- -------
-------- -----
-----
-------- -------
------ --- ----
------------ ----- -- - ------ ----
----- ----------------
--------- ------
--------
- ------
- -------
------
-------
----
-------- ---- --- ------
------------ ------- - ---- -- --- ------
---------
- ------------------
----------
----
------------ ----------- ----------
-------
----- -------
------
----- --------------------
-----
-------- ------- - --- -----
------------ ------- - --- ---- ---- --- ----- ------------
-----------
- ----- ------
--- ------
--------- ----
-------
----- --------------------
----------
----
------------ ----------- ----------
-------
----- --------------------
------------
-----
----- --------
-----------
---
----- ---------
-----
----- --------
------
----- --------
---------
----- --------以上是一个简单的例子，它定义了一个 /users 路径，包含一个 GET 请求方法和一个 POST 方法。每个请求都包括描述、参数、响应状态码等信息。
3. 将 Swagger 集成到应用中
在你的 Express 应用中添加以下代码：
-- -------------------- ---- -------
----- ------- - -------------------
----- --- - ----------
----- --------- - ------------------------------
----- ------------ - -------------------------
----- ------- - -
----------- -
-------- --------
----- -
------ --- -----
-------- --------
--
--
-- --------------------------- ------- ------
----- ----------------- ------------------
--
----- ----- - ----------------------
-------------------- ---------------- ------------------------
-- ------
---------------- -- -- -
------------------- ------- -- ---- -------
---4. 访问 Swagger UI
在浏览器中输入 http://localhost:3000/api-docs，你将看到 Swagger UI 页面。您可以使用该页面测试 API、查看规范文件和生成客户端 SDK。
总结
Swagger 是一种流行的 API 设计和文档化工具，它可以根据描述 RESTful API
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/651afe6295b1f8cacd2c1b2e