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 中的 JSON 模式规范标准和 AsyncAPI是不同的，例如定义方法 discriminator是不同的。