Swagger UI 本地主机教程： 如何在本地使用 Swagger UI？

Swagger UI 是一种工具，允许你查看以 Swagger 规范 (OpenAPI Specification, OpenAPI 规范) 生成的 API 文档。 Swagger UI 也为你提供在线和离线版本，但由于各种原因，你可能需要在本地使用 Swagger UI 打开生成的 Swagger 规范文件。 在本文中，我们将向你展示如何在本地运行 Swagger UI，如果你在此过程中遇到一些问题，请继续阅读。

什么是 Swagger UI？

Swagger UI 是一种工具，允许你以交互方式显示和验证以 OpenAPI 规范（以前的 Swagger 规范）编写的 API 定义。 通过在本地环境中设置 Swagger UI 并导入 API 定义，开发人员可以在实时检查 API 规范的同时进行开发。

为什么要在本地使用 Swagger UI？

虽然 Swagger UI 提供了 SaaS 版本，但许多用户更喜欢将其安装在本地机器上并设置本地 Web 服务器。 因此，许多用户都在本地主机 (localhost) 上访问 Swagger UI。 那么，在本地使用 Swagger UI 有什么优势呢？ 让我们详细探讨这些好处。

在本地环境中使用 Swagger UI 的主要原因包括：

• 实时 API 开发： 在本地开发 API 时，必须能够实时检查 API 定义。
• 离线文档参考： 本地使用允许你离线参考 API 文档，而无需网络连接。
• 增强的隐私： 本地使用可确保你正在开发的 API 的私密性，无需外部发布，使其远离第三方访问。
• Mock 服务器测试： 你可以设置和测试本地 Mock 服务器来验证 API 的功能。
• 迭代 API 定义： 本地使用使你能够对 API 定义进行迭代更改，并每次检查其影响。
• CI/CD 管道验证： 本地验证成为你 CI/CD 管道的一部分，确保 API 在开发过程中的可靠性和质量。

在本地使用 Swagger UI 的优势

下面列出了在本地环境中使用 Swagger UI 的优点，但最好根据具体情况决定是使用基于云的服务还是在本地使用。

• 可以离线使用，因为它不依赖于互联网环境
• 易于开发，因为你可以实时检查本地 API 定义
• 无需将正在开发的 API 暴露给外部世界。
• 你可以在本地设置一个模拟服务器，这样你就可以检查操作。
• 响应速度很快，因为它不依赖于开发机器的规格。
• 通过按照自己的节奏开发来提高生产力
• 比使用共享服务器更安全
• 易于同步 API 定义和实现

如何在本地使用 Swagger UI？

那么，如果我想在本地使用 Swagger UI 应该怎么办？ 接下来，我将详细解释如何在本地使用 Swagger UI。

安装 Swagger UI 并设置开发环境

首先，你需要下载 Swagger UI 并将其安装在本地计算机上。 最新版本是首选。 Swagger UI 仓库在 GitHub 上管理，所以请使用以下命令安装它。

git clone https://github.com/swagger-api/swagger-ui.git

然后使用如下命令设置你的开发环境：

cd swagger-ui
npm run dev

通过在浏览器中访问 http://localhost:3200/ 即可启动 Swagger UI。

设置本地 Web 服务器

接下来，为了启动 Swagger UI，你需要使用以下命令行准备一个 Web 服务器。 这里我们将使用 Node.js 的 http-server 模块。

npm install -g http-server 

启动 HTTP-server 并启动 Swagger UI

导航到 Swagger 规范文件所在的目录，在该目录中启动 http-server，并使用如下命令启用 CORS：

cd {your-oas-document-dir}
http-server --cors

然后，当你访问 http://localhost:8080 时，Swagger UI 将启动。

准备 Swagger 规范文件

接下来，准备 Swagger 规范文件。 通常，Swagger 规范文件以 Json 或 Yaml 格式编写。 例如，假设你将它写在一个名为 swagger.yaml 的文件中。 Swagger 规范文件的 URL 是 http://localhost:8080/swagger.yaml。

此外，如果你想了解更多关于 Swagger 规范文件的信息或更改 Swagger UI URL 的默认路径，请参考以下文章：

在 Swagger UI 中输入 Swagger 规范文件的 URL 并打开它

然后，在 Swagger UI 屏幕上，在顶部的输入框中的上述 SPEC URL 中输入 swagger.yaml URL，然后单击“Explore”按钮以显示本地 API 定义文档。

Apifox： 更高效地管理你的 API

使用 Swagger UI 时，你需要构建一个服务器并设置一个 URL，这可能很麻烦。 如果你正在寻找一个更简单的解决方案，我们建议你使用 Apifox，一个易于使用的 API 管理工具。

Apifox 可以直接读取 Swagger Json 和 Yaml 文件，并快速测试你的 API。 你还可以使用其共享功能来生成和共享漂亮的 API 文档。

轻松将 JSON 和 YAML 导入 Apifox

Apifox 支持导入 YAML 和 JSON 格式的数据，因此你可以完全解析这些文件，并将 API 的数据完全导入 Apifox 进行测试。

在 Apifox 中打开你的项目设置，单击 “导入数据”，选择 “OpenAPI/Swagger”，然后将 YAML 文件拖到 Apifox 中。

使用 Apifox 测试你的 API

将 API 的数据导入 Apifox 后，你可以通过单击左侧的 “API” 选项卡来查看导入的 API。 如果你想测试特定的 API 端点，你可以单击它，在直观的 UI 中填写参数，“发送” 请求，并获取 响应。

使用 Apifox 生成和共享 API 文档也非常容易。 以下是 Apifox 生成的示例 API 文档：

关于 Swagger UI Localhost 的常见问题

如何在本地主机上访问 Swagger UI？

• 在本地运行你的 API 项目，然后在浏览器中导航到 http://localhost:<port>/swagger。 端口通常是 5000 或 5001。

Swagger 本地主机的 URL 是什么？

• 默认 URL 是 http://localhost:<port>/swagger，其中 port 是你的 API 在本地运行的端口。

如何在本地托管 Swagger 文档？

• 在你的启动代码中启用 Swagger，启动 API 项目，然后导航到 /swagger 端点以查看 UI。

localhost .NET core 的 Swagger URL 是什么？

• 对于 .NET Core API，Swagger URL 通常是 http://localhost:<port>/swagger/v1/swagger.json

总结

Swagger UI 是开发 API 时有用的工具，但对于更高级的 API 生命周期管理，它具有局限性。 Apifox 为 API 开发提供一站式功能，例如 API 定义、自动文档生成、测试、监控和共享。

Apifox 允许你导入 Swagger 和 OpenAPI 规范文件，并以交互方式测试你的 API。 共享功能允许你创建精美的文档并与你的团队共享。 如果你想简化你的 API 开发过程，Apifox 是适合你的解决方案。 通过将其与 Swagger UI 结合使用，你将能够实现更强大的 API 生命周期管理。