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

问题描述

我们有很多微服务公开了它们的 API，我们有 API 优先的方法。每个服务都有自己的 OpenApi3.0 规范文件，大部分为 yaml 或 json 格式，位于它们自己的 git 存储库中。

但是，与其他公司一样，我的团队和其他内部团队在发现 API 及其相关文档方面遇到了麻烦。我想建立一个可以呈现所有 API 规范并使事情易于发现的中心位置。可能与 Stripe 或 Twitter 文档标准相当。

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

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

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

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

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

解决方法

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

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