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