Your AsyncAPI specs deserve more than a repo. Give them discoverability.

Most teams write specs and forget them. Here's how to turn them into a catalog your whole org can browse, search, and understand.

I talk to a lot of teams building event-driven architectures. And something I keep seeing is this: teams invest real effort into writing AsyncAPI specs, they get the contracts right, they validate the schemas... and then the spec file sits in a GitHub repo and nobody outside the immediate team ever looks at it.

I believe that’s a missed opportunity.

The spec-in-a-repo problem

Think about what happens when you write an OpenAPI spec for a REST API. You point Swagger or Redoc at it and suddenly your team has browsable, searchable, interactive documentation. The spec becomes the foundation for a developer experience. It's been this way for years. It works.

Now think about what happens when you write an AsyncAPI spec. You commit it. It sits in the repo. Maybe it's in a /docs folder, maybe it's at the root. Someone on the team knows it's there. Most people don't.

I've had this conversation probably a hundred times now. A team tells me "we have AsyncAPI specs" and I ask "can a new engineer on another team find your OrderCreated event and understand who produces it, who consumes it, and what the schema looks like?" And the answer is almost always no.

The spec exists. The discoverability doesn't.

What I keep hearing from teams

I'm of course biased here, I built EventCatalog to solve exactly this problem. But the patterns I hear are real, and they come up whether people end up using EventCatalog or not.

"We have the same event built twice." A platform team at a 300-person engineering org told me their biggest headache was that many events looked the same across teams. Nobody duplicated on purpose. They just couldn't see what already existed. Two teams, two Kafka topics, two nearly identical schemas, discovered months later.

"No one knows what we have." This one comes up in almost every conversation. Specs in repos, schemas in registries, documentation in Confluence, context in Slack threads, and the rest lives in someone's head. A new engineer joins and spends weeks piecing together how services actually communicate.

"A schema change broke three things downstream." A producer changes a field type. It's a small change. But three consumers downstream are affected and nobody connected the dots until production alerts started firing. The spec was updated, but nobody was watching the spec.

These aren't exotic problems. They're the normal state of event-driven architectures once you get past a handful of services.

AsyncAPI is doing the hard part already

I want to be clear: I think AsyncAPI is genuinely valuable. If you're building event-driven systems and you're not using AsyncAPI (or something like it), you're making life harder for yourself.

What AsyncAPI gives you is a standard, machine-readable way to describe your async APIs. Channels, messages, schemas, server details. It's to event-driven APIs what OpenAPI is to REST. And the ecosystem around it is growing, there's validation, code generation, testing tools, all built on top of the spec.

The contract is the hard part. Getting teams to actually sit down and describe their events in a structured way... that's the real work. If you've done that, you've done the heavy lifting.

But here's what I think a lot of teams miss: the spec is an input, not an output. It's not the end product. It's the raw material for something much more useful.

Turning specs into something the whole org can use

This is where I think the real value lives. You take those AsyncAPI files and you feed them into something that makes them browsable, searchable, and visual. Something that shows relationships between services. Something that tracks how schemas change over time. Something that tells you who owns what.

With EventCatalog, you point the AsyncAPI plugin at your spec files and it generates the catalog automatically. Services, events, channels, schemas, domains, all mapped out with visualisations.

generators: [
  [
    '@eventcatalog/generator-asyncapi',
    {
      services: [
        { path: './asyncapi/order-service.yml', id: 'order-service' },
        { path: './asyncapi/payment-service.yml', id: 'payment-service' },
      ],
      domain: { id: 'commerce', name: 'Commerce', version: '1.0.0' },
    },
  ],
]

The specs stay the source of truth. Every time you rebuild, the catalog picks up changes. Version history is tracked. Custom documentation you add to any resource survives regeneration.

But beyond the tooling, I think the shift in mindset is what matters most. You stop thinking of the spec as "the documentation" and start thinking of it as the seed for a living, organisation-wide view of your architecture.

A few things I've seen work well

Automate the catalog from CI/CD. The AsyncAPI plugin can fetch specs by URL. That means on every merge to main, your CI pipeline pulls the latest specs and rebuilds the catalog. No manual steps. No drift. The catalog is always up to date because it's generated from source.

services: [
  {
    path: 'https://raw.githubusercontent.com/your-org/order-service/main/asyncapi.yml',
    id: 'order-service',
  },
]

This is worth exploring if you have specs scattered across multiple repos. You can pull them all into one catalog automatically.

Mix async and sync in one view. Most orgs don't have a purely event-driven architecture. They have REST APIs, maybe some GraphQL, and async events living together. EventCatalog supports OpenAPI alongside AsyncAPI, so you can see how a REST endpoint triggers a Kafka event that flows to three downstream consumers. All in one place. I think this is important because the real architecture is never just one thing.

Let governance emerge naturally. When your specs are in a catalog with ownership tracking and version history, you get governance without building a governance programme. You can see who owns what. You can see when schemas change. You can spot when a team changes a contract that others depend on. It's not governance as bureaucracy, it's governance as visibility.

Something to think about

If you already have AsyncAPI specs, you might be closer than you think to having a proper catalog for your architecture. The specs are the hard part. Making them discoverable is surprisingly straightforward.

And if you don't have AsyncAPI specs yet, that's fine too. EventCatalog works with manually authored documentation. But I'd encourage you to think about the spec-first approach. 5 minutes writing a spec can save a lot of pain later when someone needs to understand your events and you're not around to explain them.

I'd love to know how other teams are getting value from their AsyncAPI specs. Are you just using them for validation? Code generation? Something else entirely? The more I talk to teams, the more I think we're still early in figuring out the best workflows here.

If you want to try the AsyncAPI + EventCatalog combination, you can get started in a few minutes:

npx @eventcatalog/create-eventcatalog@latest my-catalog --template asyncapi

Or play with it at try.eventcatalog.dev.