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

Question

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

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

• http://editor.swagger.io/?raw=https://raw.githubusercontent.com/path/to/file.yaml
• https://app.swaggerhub.com/apis/(用户名)/(api-名称)/(api-版本)

两种方法都有效，但它们都在左侧打开一个编辑器，显示 YAML 文件的内容，恕我直言，浪费了大量的屏幕空间。实在不是我想要的。是否有一个选项可以在不打开编辑器的情况下显示 OpenAPI 文档？与https://petstore.swagger.io/的操作类似，无需打开编辑器。

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

谢谢，克里斯托夫

Answer 1

如果您使用 SwaggerHub，请替换/apis/URL/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

将其加载到公共 Swagger UI 演示中。Swagger UI 在没有编辑器部分的情况下呈现 API 文档。