swagger - 如何记录同步和异步 API 的混合？我们使用 AsyncAPI 或 OpenAPI 还是两者兼而有之？

Question

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

Answer 1

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

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

Answer 2

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

未来更加光明，请查看https://github.com/asyncapi/bindings/issues/2并参与有关 HTTP 绑定的讨论，我们可以在其中启用 OpenAPI 的路径项对象的重用，以便您可以重用更多的 OpenAPI异步API。