documentation - 使用 OpenAPI 规范的 API 文档，在一个中心位置有多个规范

Question

我们有很多微服务公开他们的 API，我们有一个 API 优先的方法。每个服务都有自己的 OpenApi3.0 规范文件，主要是 yaml 或 json 格式，位于它们自己的 git repo 中。

然而，就像其他公司一样，我的团队和其他内部团队在发现 API 和围绕它的文档方面遇到了麻烦。我想建立一个可以呈现所有 API 规范并使事物易于发现的中心位置。可能与说 Stripe 或 twitter 文档标准相当。

到目前为止，我找到了几种方法来实现它：

1. 使用 React 框架分别为每个规范渲染 Redoc 组件。使其可扩展，但跨服务搜索可能很困难。

2. 使用一些预先存在的工具合并所有 api 规范并将其转换为 MarkDown 以在 Slate 中显示或使用 Docusauras 和 React Redoc 东西。使用https://www.npmjs.com/package/openapi-merge-cli和 widdershins 与 slate 合并。在拥有多个 api 的公司中，我认为使用这种方法进行扩展将是一个有趣的挑战。

我不想依赖 SwaggerHub，因为它将我与特定的东西联系在一起。同样，我正在寻找具有允许商业用途的许可证的开源东西。

很想得到一些建议/经验，或者是否存在类似的东西，我可以避免重新发明轮子。

标签： documentationopenapiapi-docredoc

Answer 1

似乎还没有很多开源解决方案。在 repo 中，Redoc 有一个示例，说明如何在此处组合多个服务的规范文件。

这里还有另一个示例，其 API 稍好一些。它还与 Docker 打包在一起，这应该使启动和运行更容易。