什么是 Swagger？
Swagger 是一个用于建立、设计、编写和测试 RESTful API（即遵循 REST 架构风格的 API）的软件框架。它是一种开放源码的工具，可以让你轻松地编写文档、定义 API 规范、自动生成客户端 SDK 和服务器端代码。
为什么要使用 Swagger？
当我们编写 API 时，不管是自己使用还是给别人使用，良好的文档都是重要的。Swagger 提供了一个标准的文档编写方式，能够使我们轻松创建清晰易懂的 API 文档。
同时，Swagger 还提供了一种自动生成客户端 SDK 和服务器端代码的方式，可以减少我们的开发时间和极大提高我们的效率。
如何在 Express.js 上集成 Swagger UI？
在这里，我们将介绍如何在 Express.js 应用中集成 Swagger UI。Swagger UI 是一个用于查看和测试 Swagger 规范的界面，在 Express.js 中使用它能够使我们的 API 文档更加生动直观，更容易被人们所理解。
安装 Swagger UI
我们需要安装 swagger-ui-express 这个中间件，它是 Express.js 和 Swagger UI 的适配器。
使用 npm 安装：
npm install swagger-ui-express --save
创建 Swagger 规范
我们需要创建一个 Swagger 规范文件，这个文件描述了我们的 API 的基本信息，包括接口路由、请求参数等。
在这里，我们以 express.js 的 Restful API 为例，我们定义服务的路由在 API 文档中的样式。
-- -------------------- ---- -------
-
---------- --------
------- -
-------- ----------- ------- -----
---------- --------
-------------- ---- ------------- --- ---------- ------- ----
--
---------- --
------ ------------------------
-------------- ------ ------ --- ------------
---
-------- -
------------- -
------ -
------- ----------
---------- ---- --- -------
-------------- -----------
------------ -
------ -
-------------- ---- ----- --------- --------------
---------- -
------------------- -
--------- -
------- --------
-------- -
------- ---------
------------- -
------- -
------- --------
--
-------- -
------- --------
--
------------ -
------- --------
--
------------ -
------- --------
-
-
-
-
-
-
-
-
-
-
-
-导入 express.js 依赖
我们需要安装 express.js 所需的依赖：
npm install express body-parser –-save
编写 Express.js 应用
接下来，我们需要编写 Express.js 应用，设置 Swagger UI 并启动 Express.js 服务。
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ---------- - ----------------------- ----- --------- - ------------------------------ ----- --------------- - ------------------------- ----- --- - ---------- ------------------------------- --------- ----- ---- --------------------------- -------------------- ---------------- ---------------------------------- ----- ---- - ---------------- -- ----- ----- ------ - ---------------- -- -- - ------------------- -- ------- -- ---- --------------------------- ---
总结
在本篇文章中，我们介绍了 Swagger 的基本概念，并指导了如何在 Express.js 应用中集成 Swagger UI，用于管理 API 文档。
正确地使用 Swagger，可以让我们更加快捷高效的完成 API 文档管理，这是一个非常重要的工作，对我们的开发工作和协作非常有帮助。
参考
- Swagger 官网：https://swagger.io/
- Swagger UI Express 官网：https://github.com/scottie1984/swagger-ui-express
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64c079109e06631ab9cc9d4d