How to define events in OpenAPI / Swagger spec?

Question

How can an event-driven microservices architecture be defined using the OpenAPI / Swagger specification? For events, it is important to document the event payload passed among different services, even when they are not accessed via HTTP paths.

Everything I've seen is API-based via HTTP paths, so I'm wondering now to implement this with OpenAPI / Swagger spec?

Answer 1

OpenAPI 3.1

OpenAPI Spec 3.1 supports events via the top level webhooks property. OpenAPI Spec 3.1 defines webhook support here:

• Spec Definition: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
• Spec Example: https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml

OpenAPI 3.0

For tools that handle OAS 3.0, defining event bodies using schemas only is still useful as such definitions can be used by codegen tools like OpenAPI Generator to auto-generate schema objects for languages like Java, Swift, Go, etc.

OpenAPI 2.0 / Swagger 2.0

For Swagger Spec 2.0 (aka OpenAPI Spec 2.0), you can include definitions in the Swagger spec as mentioned by alamar. Swagger Codegen will automatically create model classes for these definitions, even if they are not associated with any paths. I build and maintain a Swagger Spec/Codegen-built SDK in Go for the RingCentral API that has events like this. You can see the auto-generated classes/structs Swagger Codegen builds in the following folder, filtering for the 20 files that end in _event.go. These are currently created using swagger-codegen 2.3.1.

• Generated files: https://github.com/grokify/go-ringcentral/tree/master/client
• Codegen info: https://github.com/grokify/go-ringcentral/tree/master/codegen

If you have multiple event types, having an event property that can distinguish message types you are receiving can help parse it into the correct event class/struct. In Go, you can unmarshal the data twice, once into a generic struct to peek at the event type property, and then a second time for the actual event type.

I also maintain a collection of example events and parsing code in the Chathooks webhook reformatter project you can use for reference. You can see the example events and (hand-rolled) language definitions here:

• Examples: https://github.com/grokify/chathooks/tree/master/docs/handlers
• Definitions: https://github.com/grokify/chathooks/tree/master/src/handlers

AsyncAPI

An alternative to OpenAPI is to use AsyncAPI is a specification for event driven architectures. It is protocol agnostic so can be used with Kafka, Websocket, MQTT, AMQP and anything else based on messaging.

Answer 2

If you have strongly typed events, you could use reflection to publish the structure of the events and that should be sufficient for a client of your microservice.

If you have some event descriptors (xml or similar) used to re-hydrate the events from the event store/event log then you can publish those.

Otherwise I don't know of any tools that would work like Swagger but for events.

Answer 3

If you are using Java, there is an alternative. I never tested this, but this idea could guide you for a solution for another platforms.

You can use the "good" and old Javadoc for that and the Swagger module from Enunciate, as explained here:

You can generate swagger-ui from Javadoc by using Enunciate, which has a Swagger module

It's just a maven plugin. In the final, you have a Full HTML documentation of your services, scraped from your JavaDocs..

Answer 4

I think you can have definitions in Swagger even if they aren't used by any endpoints. Just declare any types that you need in a dedicated section, e.g. "definitions". You can refer ones that you're using in the endpoints as e.g. "$ref": "#/definitions/User", as per main Swagger live example.

I expect that code will be generated for them, so you can write tests against any of definitions.