如何记录同步和异步 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 规范的标准是不同的，例如定义方法discriminator不同。