如何记录同步和异步 API 的混合？我们使用 AsyncAPI 或 OpenAPI 还是两者都使用？

如何解决如何记录同步和异步 API 的混合？我们使用 AsyncAPI 或 OpenAPI 还是两者都使用？

考虑一个由多个端点组成的应用程序，一些是同步的，另一些是异步的，遵循事件驱动架构，以 Kafka 作为消息代理，与其他微服务通信。 这些 API 的文档标准应该是什么？我们是否需要为异步（使用 AsyncAPI）和同步 API（使用 OpenAPI）创建单独的文档页面，或者有没有办法将两者结合在一个文档中？我在网上读到 AsyncAPI 是异步 API 的文档标准，OpenAPI 应该用于普通的同步 Rest API，但如果我们在单个应用程序中混合使用不同类型的 API，则找不到任何相关链接. 如果您对此有任何帮助/指导，我将不胜感激。

解决方法

在我的公司，我们同时使用 OpenAPI 和 AsyncAPI 以及共享 Schema 对象。 Schema Object 可以移动到单独的文件中，然后由两个 API 规范中的 refLink 使用。

请注意，OpenAPI 和 AsyncAPI 中 JSON Schema Specification 的标准是不同的，例如定义 discriminator 的方法不同。

,

现在，您可以像@kris13 在他的回答中所写的那样，在 AsyncAPI 和 OpenAPI 文档之间重用 JSON 模式。 AsyncAPI 解析器有一个插件可以解析 OpenAPI 模式。 AsyncAPI 支持多种 schemaFormats。

未来更加光明，看看 https://github.com/asyncapi/bindings/issues/2 并参与有关 HTTP 绑定的讨论，我们可以在其中启用 OpenAPI 的 Path Item Object 的重用，以便您可以在 AsyncAPI 中重用更多的 OpenAPI。