AsyncAPI is a machine-readable interface definition language for asynchronous messaging APIs. It describes both message content and how a service communicates through a messaging system; it applies beyond event-driven architectures. Its contract can support documentation, validation, code generation, and compatibility checking. section 8.3.5
An AsyncAPI document defines three core parts:
- Channels: the message channels a service uses. section 8.3.5
- Messages: the types and schemas of messages exchanged over those channels. section 8.3.5
- Operations: how the service participates in message flow, including sending or receiving. section 8.3.5
Use AsyncAPI when teams need a precise, shareable contract for a messaging API. It is useful for consistent tooling across services, though it is not as universal as OpenAPI is for REST APIs. section 8.3.5 section 8.4
Listing 8.3 An excerpt from an AsyncAPI document that defines a service publishing events such as CustomerCreatedEvent to the com.example.Customer channel.
channels:
com.example.Customer:
address: com.example.Customer
messages:
com.example.CustomerCreatedEvent:
$ref: "#/components/messages/com.example.CustomerCreatedEvent"
...
messages:
com.example.CustomerCreatedEvent:
headers:
$ref: "#/components/schemas/HeadersNotDocumented"
payload:
schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
schema:
$ref: "#/components/schemas/com.example.CustomerCreatedEvent"
name: com.example.CustomerCreatedEvent
title: com.example.CustomerCreatedEvent
...
components:
schemas:
com.example.CustomerCreatedEvent:
title: CustomerCreatedEvent
type: object
properties:
id:
type: string
examples:
- id: string
operations:
io.eventuate.exampleapp.events.publisher.CustomerEventPublisherImpl:
action: send
channel:
$ref: "#/channels/com.example.Customer"
messages:
- $ref: "#/channels/com.example.Customer/messages/com.example.CustomerCreatedEvent"
The YAML excerpt shows a service publishing CustomerCreatedEvent on the com.example.Customer channel and referring to a schema for its payload. section 8.3.5

