When we first started documenting domain events, we used OpenAPI because it was already part of our engineering practices. It worked well enough to get us started, but as our event-driven platform grew, we found ourselves forcing a request/response specification to describe asynchronous messaging.

We adopted AsyncAPI to publish event contracts across our backend platform, where events are consumed by game teams, Data Science, QA, and other backend services. Using Springwolf, we automatically generate AsyncAPI specifications from our Spring Boot applications. However, we quickly discovered that generated specifications were not the same as published contracts. They exposed Java implementation details, framework-specific wrappers, and internal metadata instead of the domain language our consumers expected.

In this session, I'll share how we transformed generated specifications into published contracts. We'll cover the customisations we made to produce consumer-friendly documentation, how we integrated AsyncAPI generation into our CI pipeline, and how every contract change is automatically surfaced through a pull request for architectural review before becoming the published contract. This governance process helps us evolve event contracts safely across independently deployed services with multiple downstream consumers.

I'll also discuss the limitations we encountered. Producer discovery still relies on manual annotations, which means some producers might be missed if they are not properly annotated, and we intentionally focused on documenting the business contract rather than every messaging platform capability.

This is not a deep dive into the AsyncAPI specification. It's a practical engineering story about introducing AsyncAPI into an existing platform, the trade-offs we made, the mistakes we learned from, and how generated specifications became trusted contracts shared across teams.

Audience Takeaways
Recognise when OpenAPI is no longer the right fit for event-driven APIs.
Learn how to customise generated AsyncAPI specifications to communicate in domain language rather than implementation details.
See a practical CI-based governance approach for reviewing contract changes before publication.
Understand the difference between generated documentation and a published contract.
Learn where automation helps—and where manual governance is still required