AsyncAPI and NServiceBus

[JoostvdB94]

Describe the feature.

AsyncAPI is an open-source specification that provides a standard way to define:

• Event-driven services
• Message brokers
• Topics, channels, and event payloads

It makes it easier to document, understand, visualize, and generate code for message-based systems.

Is your feature related to a problem? Please describe.

NServiceBus already supports native integration. This requires at least 1 header, but in some cases several.
Exchanging the requested and published messages and it's headers using a language-agnostic interface specification would greatly increase the inoperability with languages other than C#.

Describe alternatives you've considered

I already looked into the extension points provided by NServiceBus, but couldn't find a way to list all messages that are sent by an application.

Another option could be to be able to generate a AsyncAPI document from ServiceInsight, as it has information on published and subscribed events.

Additional Context

We have created two samples to demonstrate how it can be used with NServiceBus:

• Simple AsyncAPI sample
• AsyncAPI with custom message conventions sample

There was a choice of two .NET AsyncAPI packages to use:

• Saunter
• Neuroglia AsyncAPI

Neuroglia AsyncAPI was chosen as it supports the latest version of AsyncAPI.

Here are some questions that we are interested in understanding more:

• In what context do you use AsyncAPI?
• Are there any specific use cases that need to be supported?
• Do you publish/register the generated document schemas? If so, where?

[danielmarbach]

@JoostvdB94 a while ago, I created this spike. I haven't updated this for a while, but it might be a good starting point to achieve some of the things you are asking for.

[jpalac]

@JoostvdB94 we have updated the feature description with some extra content and links to 2 samples.

[jpalac]

Hey @JoostvdB94 - just checking in to see if you had a chance to review the two samples.
Do they align with your use case, or did we miss the mark?
If not, what’s missing? And are there other aspects of AsyncAPI you’d like us to consider when it comes to integrating with NServiceBus?

Looking forward to hearing your thoughts.

[JoostvdB94]

Thanks @jpalac,

The https://docs.particular.net/samples/asyncapi/simple/ example already solves some of the features. As is mentioned in the sample, differentiating between published and subscribed events is hard.
I can see how IMessageHandler<TEvent> could play a role in searching for subscribed events (using reflection perhaps?)

But as is demonstrated in the second link, using conventions may be a more declarative way of doing this. This is not really a plug-n-play way of adding AsyncAPI.

Ideally, a plug-n-play way of adding AsyncAPI (without additional code changes) would provide the best developer experience. I see however how this is hard, as sending messages is not structured via their own structured class (such as using clients with specialized methods).

Maybe combining both worlds can be a solution?

1. Get all events from the messageMetadataRegistry
2. Match all events used in any IMessageHandler from this collection and save them as events that the component subscribes to (so publish-events in AsyncAPI)
3. Mark all other events in the registry as events that de component publishes (so subscribe-events in AsyncAPI)

Could that be one of default choices that NServicebus provides? So the user has the choice:

• Plug-n-play: Use the solution proposed above (this may be partly incorrect if there are unused events in the registry)
• Declarative: Use custom message conventions

[JoostvdB94]

A stretch goal would be to ingest and generate code based on an other component's AsyncAPI. This way, connecting to another service would become easier to implement, just like NSwag can do most of the scaffolding when connecting to an HTTP API based on an OpenAPI spec.

The solution now focusses on publishing the AsyncAPI document for documentation purposes. This is great if your goal is to document AsyncAPI's centrally in Pact or Backstage (as we do ourselves).

[lailabougria]

Hi @JoostvdB94, thanks for considering the samples, and for sharing your thoughts and suggestions. We’ll take your feedback into account when considering next steps and we’ll keep you posted.