如何在 GitHub (readme.md) 上发布 OpenAPI 文档的最佳方式？

Question

我在 GitHub 上托管了一个项目。为了记录 API 我正在使用 OpenAPI 规范。现在我想在 readme.md（在 GitHub）上添加一个 link，将我的访问者引向 OpenAPI 文档以获得良好的用户体验。

据我所知，我有两个解决方案：

• http://editor.swagger.io/?raw=https://raw.githubusercontent.com/path/to/file.yaml
• https://app.swaggerhub.com/apis/(username)/(api-name)/(api-version)

这两种方法都有效，但它们都在左侧打开一个编辑器，显示 YAML 文件的内容，恕我直言，浪费了一个重要的屏幕 space。不是我真正想要的。是否有一个选项可以在不打开编辑器的情况下显示 OpenAPI 文档？与未打开编辑器的 https://petstore.swagger.io/ 所做的类似。

或者...是否有一个选项可以直接在 GitHub 上显示 OpenAPI 文档？

谢谢，克里斯托夫

Answer 1

如果您使用 SwaggerHub，请将 URL 中的 /apis/ 替换为 /apis-docs/ 以仅查看没有编辑器部分的 API 文档。例如：

https://app.swaggerhub.com/apis-docs/swagger-hub/registry-api/1.0.47

或者，如果您的 OpenAPI 定义托管在别处（例如 GitHub），您可以使用
https://petstore.swagger.io/?url=https://path/to/file.yaml

将其加载到 public Swagger UI 演示中。 Swagger UI 呈现 API 没有编辑器部分的文档。