API 文档使用 OpenAPI 规范和多个规范在一个中心位置

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，因为它将我与特定的东西联系在一起。同样，我正在寻找具有允许商业用途的许可证的开源东西。

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

Answer 1

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

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