Swagger-UI 是一个 API 文档管理工具，它允许开发人员在浏览器中浏览和测试 API，同时提供了多种内容展示、交互和调试工具。Express.js 是一款灵活且功能强大的 Node.js web 应用框架，它可以轻松构建 Web 服务器和 API。在本文中，我们将介绍如何将 Swagger-UI 集成到 Express.js 项目中，以更加高效地输出 API 文档。
什么是 Swagger-UI？
Swagger-UI 是 Swagger 生态系统中一名负责 API 文档管理的成员。它可以生成交互式 API 文档，让用户可以在浏览器中通过 UI 操作来浏览和测试 API，而不需要额外的工具。具体而言，Swagger-UI 可以生成 API 的参数列表、请求头、响应列表、错误信息和状态码，以及各种交互式展示工具，比如请求发送器、响应查看器和错误解析器。
为什么要集成 Swagger-UI？
集成 Swagger-UI 可以让我们更加高效地输出 API 文档，从而提高开发速度和代码质量，同时也可以提升用户的使用体验。在以下几种情况下，集成 Swagger-UI 尤为重要：
- 当我们需要快速查看和测试 API 时，可以直接在浏览器中打开 Swagger-UI，无需打开 Postman 或其他工具；
- 当我们需要添加、修改、删除 API 时，可以直接在 Swagger-UI 中修改，并通过测试来检查其它 API 是否受到影响；
- 当我们需要向用户展示 API 文档时，可以直接将 Swagger-UI 部署在服务器上，用户可通过访问链接来查看 API 文档。
如何集成 Swagger-UI？
在本节中，我们将介绍如何在 Express.js 项目中集成 Swagger-UI。
第一步是安装依赖：Express.js 和 Swagger-UI。
--- ------- ------- ------------------
第二步是设置 Express.js 应用程序。
----- ------- - ------------------- ----- --------- - ------------------------------ ----- --------------- - -------------------------- ----- --- - ---------- -------------------- ---------------- ---------------------------------- ---------------- -- -- - ------------------- ---------- ---
在此示例中，我们首先引入 Express.js 和 Swagger-UI 的依赖项，然后设置应用程序使用 swaggerUi.serve 和 swaggerUi.setup。swaggerUi.serve 将公开 /api-docs 路由，而 swaggerUi.setup 将设置 Swagger-UI 的界面。最后，我们将服务器监听 3000 端口。
第三步是编写 Swagger JSON 文件。
Swagger JSON 文件是 Swagger-UI 的配置文件，其中包含了所有 API 的详细文档信息。下面是一个示例文件：
- ---------- ------ ------- - -------- ----------- ----- ---------- ------- -- ------- ----------------- ----------- ---- ---------- - ------ -- ---------------------- --- -------- - ------------ - ------ - ------- - ---------- -- ---------- ------ --- ------ -------------- ----- --- ---- ----- --- ---- ---- - ------- ---------- ----------- - ------------------ -- ------------ - ------ - -------------- ----------- ---------- --------- - ------- --------- ------------- - ---------- - ------- -------- - - - - - - - - -在此配置文件中，我们定义了一个 Greeting API，其可以从 /greeting 路径访问。API 的详细信息都包含在 get 属性中。这个 API 将返回一个 JSON 响应，其中包含了一个 message 字段。
最后一步是启动服务器并查看 Swagger-UI。
在命令行中输入以下命令：
---- ------
在浏览器中打开以下 URL：
------------------------------
如果一切正常，您将在浏览器中看到 Swagger-UI 界面。
总结
Swagger-UI 是一个功能强大的 API 文档管理工具，通过集成 Swagger-UI，我们可以更加高效地输出 API 文档，从而提高开发速度、代码质量和用户使用体验。在本文中，我们详细介绍了在 Express.js 应用程序中集成 Swagger-UI 的步骤，并提供了示例代码和 Swagger JSON 文件。希望这篇文章能够为您的开发工作带来帮助和指导。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/6644ea67d3423812e42d0e8c