How to document a mixture of synchronous and asynchronous APIs? Do we use AsyncAPI or OpenAPI or both?

Question

Consider an application consisting of multiple end-points, some synchronous and others are asynchronous following the event-driven architecture with Kafka as the message broker, communicating with other microservices. What should be the standard for documentation of these APIs? Do we need to create the separate documentation pages for asynchronous(using AsyncAPI) and synchronous APIs(using OpenAPI), or is there any way to combine the two in a single document? I've read online that AsyncAPI is the documentation standard for asynchronous APIs, and OpenAPI should be used for normal synchronous Rest APIs but could not find any relevant links on what to use if we have a mixture of different kind of APIs in a single application. I'd appreciate any help/guidance on this.

Altorelievo

Have you checked OAS3 Callback ==> swagger.io/docs/specification/callbacks – Mikamikado

Answer 1

In my company we use both OpenAPI and AsyncAPI with shared Schema objects. Schema Object could be moved to a separate file(s) and then used by refLink from both API spec.

Be aware, standards of JSON Schema Specification in OpenAPI and AsyncAPI are different, e.g. approach to define discriminator is different.

Mccaleb

Answer 2

For now, you can as @kris13 wrote in his answer, reuse JSON Schemas between AsyncAPI and OpenAPI documents. AsyncAPI parser has a plugin that can parse OpenAPI schemas. AsyncAPI supports multiple schemaFormats.

Future is more bright, have a look at https://github.com/asyncapi/bindings/issues/2 and involve in a discussion about HTTP Binding where we could enable reuse of OpenAPI's Path Item Object so you could reuse even more OpenAPI in AsyncAPI.

Mellman