v9: AsyncAPI 3.0 document generation

[slang25]

v9 stacked PR — AsyncAPI document generation

Adds a JustSaying.AsyncApi package that generates an AsyncAPI 3.0 document describing an app's publications and subscriptions — the messaging equivalent of ASP.NET Core's OpenAPI document. Stacked on #2184 (which is stacked on #2183 → #2182) — review/merge those first.

As far as I can tell no .NET messaging library has a first-party AsyncAPI story (MassTransit and aws-dotnet-messaging have nothing, NServiceBus has demo-only samples), so this would be a nice differentiator.

The metadata seam (core)

• The fluent builders now record each publication/subscription (message CLR type, destination kind + resolved name, direction, subscription group, wire name) into an IMessagingMetadataRegistry — resolved via the IServiceResolver their Configure methods already take, so it's fully opt-in and costs nothing when unused.
• Everything is captured at configure time, before the bus starts and before any AWS call. This deliberately does not build on Interrogate() — that's diagnostic-only, keyed by Type.Name, and only populated after start.

The package

• services.AddJustSayingAsyncApi(o => { o.Title = "Orders"; ... }) — registers the registry and an IAsyncApiDocumentProvider.
• Mapping: publication → channel + send operation; subscription → channel + receive operation; a multi-type queue (v9 (3/3): CloudEvents and multi-type-per-queue subscriptions #2184) → one channel with a messages map, which is exactly the AsyncAPI 3.0 model; CloudEvents registrations name messages by their CE type. Dynamic (WithTopicName(Func<...>)) destinations have no static address, so they're skipped.
• Payload schemas come from JsonSchemaExporter, driven by the app's actual serializer options — so the schema reflects the real wire contract, including the source-generated STJ path from v9 (2/3): Native AOT support #2183.
• Document model is ByteBard.AsyncAPI.NET (the official continuation of LEGO.AsyncAPI.NET) — core package only, zero transitive deps on net8.0.

Where this is heading

The provider interface (JustSaying.AsyncApi.IAsyncApiDocumentProvider) has a deliberately stable full name and GetDocumentNames()/GenerateAsync(name, TextWriter) shape: it mirrors how ASP.NET Core's build-time OpenAPI tooling resolves IDocumentProvider by name from the app's captured host. I've spiked that mechanism (HostFactoryResolver + stopApplication: true — hosted services never start, so bus.StartAsync/AWS never runs) and it works; the follow-up PR is the .targets + insider tool packaging for dotnet build-time generation.

Outstanding actions:

• Build-time tool package (MSBuild target + insider, GetDocument.Insider-style)
• Optional MapAsyncApi() ASP.NET Core endpoint
• Decide how to represent the CloudEvents envelope (payload schema is currently the data schema)
• Rebase over whichever of v9 spike: CloudEvents attributes via MessageContext (alternative to the CloudEvent<T> wrapper) #2209/v9 spike: CloudEvent<T> optional wrapper for publishing and handling #2210 ships

10 new tests + 303/304 unit (one pre-existing flaky channels test) + 10 CloudEvents green; solution builds clean with analyzers on.

Stack

1. v9 (1/3): Drop the Message base-class constraint #2182 — Foundation
2. v9 (2/3): Native AOT support #2183 — Native AOT
3. v9 (3/3): CloudEvents and multi-type-per-queue subscriptions #2184 — CloudEvents + multi-type-per-queue
4. this PR — AsyncAPI (base: slang25/v9-cloudevents)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Introduces first-party AsyncAPI 3.0 generation using messaging metadata captured during bus configuration. This PR builds on the v9 CloudEvents and multi-type queue work from #2184.

Changes:

• Adds publication/subscription metadata capture across fluent builders.
• Adds the JustSaying.AsyncApi package, schema generation, and document provider.
• Adds CloudEvents, multi-type queue, and metadata registry tests.

Reviewed changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/JustSaying.AsyncApi.Tests/WhenGeneratingWithCloudEventsAndMultiTypeQueues.cs	Tests CloudEvents and multi-type queues.
tests/JustSaying.AsyncApi.Tests/WhenGeneratingAnAsyncApiDocument.cs	Tests core document generation.
tests/JustSaying.AsyncApi.Tests/MessagingMetadataRegistryTests.cs	Tests metadata deduplication and region capture.
tests/JustSaying.AsyncApi.Tests/JustSaying.AsyncApi.Tests.csproj	Defines the AsyncAPI test project.
src/JustSaying/PublicAPI/PublicAPI.Unshipped.txt	Records new core public APIs.
src/JustSaying/Messaging/Metadata/SubscriptionMetadata.cs	Models subscription metadata.
src/JustSaying/Messaging/Metadata/PublicationMetadata.cs	Models publication metadata.
src/JustSaying/Messaging/Metadata/MessagingMetadataRegistry.cs	Stores and deduplicates metadata.
src/JustSaying/Messaging/Metadata/MessagingDestinationKind.cs	Defines destination types.
src/JustSaying/Messaging/Metadata/MessageTypeMetadata.cs	Models message type metadata.
src/JustSaying/Messaging/Metadata/IMessagingMetadataRegistry.cs	Defines the metadata registry contract.
src/JustSaying/Messaging/MessageSerialization/SystemTextJsonSerializationFactory.cs	Exposes serializer options.
src/JustSaying/Fluent/TopicSubscriptionBuilder\1.cs`	Captures topic subscription metadata.
src/JustSaying/Fluent/TopicPublicationBuilder\1.cs`	Captures topic publication metadata.
src/JustSaying/Fluent/TopicAddressPublicationBuilder\1.cs`	Captures addressed-topic metadata.
src/JustSaying/Fluent/QueueSubscriptionBuilder\1.cs`	Captures queue subscription metadata.
src/JustSaying/Fluent/QueuePublicationBuilder\1.cs`	Captures queue publication metadata.
src/JustSaying/Fluent/QueueAddressSubscriptionBuilder\1.cs`	Captures addressed-queue subscriptions.
src/JustSaying/Fluent/QueueAddressPublicationBuilder\1.cs`	Captures addressed-queue publications.
src/JustSaying/Fluent/MultiTypeQueueSubscriptionBuilder.cs	Captures multi-type queue metadata.
src/JustSaying.CloudEvents/PublicAPI/PublicAPI.Unshipped.txt	Records exposed CloudEvents APIs.
src/JustSaying.CloudEvents/CloudEventsServiceCollectionExtensions.cs	Registers CloudEvents options.
src/JustSaying.CloudEvents/CloudEventSerializationFactory.cs	Exposes the payload serializer factory.
src/JustSaying.CloudEvents/CloudEventOptions.cs	Exposes CloudEvents type lookup.
src/JustSaying.AsyncApi/PublicAPI/net8.0/PublicAPI.Unshipped.txt	Defines the new package API surface.
src/JustSaying.AsyncApi/PublicAPI/net8.0/PublicAPI.Shipped.txt	Establishes the shipped API baseline.
src/JustSaying.AsyncApi/JustSaying.AsyncApi.csproj	Defines the shipping package.
src/JustSaying.AsyncApi/JsonSchemaNodeMapper.cs	Maps exported JSON schemas.
src/JustSaying.AsyncApi/IAsyncApiDocumentProvider.cs	Defines document generation tooling API.
src/JustSaying.AsyncApi/AsyncApiServiceCollectionExtensions.cs	Registers AsyncAPI services.
src/JustSaying.AsyncApi/AsyncApiOptions.cs	Defines document options.
src/JustSaying.AsyncApi/AsyncApiDocumentProvider.cs	Builds and serializes documents.
src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs	Generates AsyncAPI channels and operations.
JustSaying.slnx	Adds the package and tests to the solution.
Directory.Packages.props	Adds AsyncAPI and JSON dependencies.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 37 out of 38 changed files in this pull request and generated 2 comments.

Suppressed comments (3)

src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs:175

• The generated AWS hostname is incorrect outside the standard aws partition. For example, cn-north-1 requires the .amazonaws.com.cn suffix (the existing SqsEndpointHelper.cs:5-12 already handles this), but this emits .amazonaws.com; the SQS block below has the same defect. Derive both hosts from the region's partition/DNS suffix instead of hard-coding it.

            document.Servers[ServerKey("sns", region, primaryRegion)] = new AsyncApiServer()
            {
                Host = $"sns.{region}.amazonaws.com",
                Protocol = "sns",
                Description = $"Amazon SNS in {region}.",

src/JustSaying/Fluent/QueueAddressSubscriptionBuilder`1.cs:152

• This metadata drops the per-subscription serializer selected by WithMessageBodySerializer (used at line 120). The generator therefore derives a payload schema from the global serialization factory even when this queue is actually deserialized by a custom serializer with a different wire contract. Capture schema/serializer information for this registration, or suppress inferred payload schemas when an override is present.

            metadataRegistry.AddSubscription(new SubscriptionMetadata(
                queue.QueueName,
                topicName: null,
                attachedQueueConfig.SubscriptionGroupName,
                attachedQueueConfig.RawMessageDelivery,
                [new MessageTypeMetadata(typeof(T), bus.MessageTypeRegistry.GetLogicalName(typeof(T)))],
                _queueAddress.RegionName));

src/JustSaying/Fluent/QueueAddressPublicationBuilder`1.cs:157

• QueueAddressQueue accepts queue URLs with a trailing slash by ignoring empty path segments, but this last-segment lookup returns an empty destination name for the same valid URL. That produces an empty channel key/address in the AsyncAPI document. Select the last non-empty trimmed segment instead.

            metadataRegistry.AddPublication(new PublicationMetadata(
                MessagingDestinationKind.SqsQueue,
                _queueAddress.QueueUrl.Segments[_queueAddress.QueueUrl.Segments.Length - 1].TrimEnd('/'),
                isDynamic: false,
                [new MessageTypeMetadata(typeof(T), subject)],
                _queueAddress.RegionName));

[Copilot]

Pull request overview

Copilot reviewed 55 out of 56 changed files in this pull request and generated 1 comment.

Suppressed comments (6)

src/JustSaying/Messaging/Metadata/PublicationMetadata.cs:25

• SQS publications are not always the bare serializer payload represented by this metadata. Both queue publication builders wrap non-raw messages as { "Message": "<serialized JSON>", "Subject": "..." } (OutboundMessageConverter.cs:51-57), while WithRawMessages() and self-describing serializers do not. Because PublicationMetadata records no wire mode, the generator always emits the CLR payload schema and therefore misdocuments every default SQS publication. Record the effective raw/envelope mode here, populate it from both queue builders, and generate the corresponding envelope schema.
  src/JustSaying.AsyncApi.BuildTools/build/JustSaying.AsyncApi.BuildTools.targets:49
• The tool writes generated paths into this cache, but only the cache itself is registered in FileWrites. Consequently dotnet clean leaves all generated AsyncAPI documents behind. Read the cache into an item list and register those paths too.

    <ItemGroup>
      <FileWrites Include="$(_JustSayingAsyncApiFileListPath)" />
    </ItemGroup>

build.ps1:29

• JustSaying.AsyncApi has a package-producing project reference to JustSaying.CloudEvents, but the release pack loop still never packs the shipping CloudEvents project. The build will produce an AsyncApi package whose declared dependency is absent from the release artifacts. Add CloudEvents to libraryProjects before packing AsyncApi.

    (Join-Path $solutionPath "src" "JustSaying.AsyncApi" "JustSaying.AsyncApi.csproj"),

src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs:203

• This hard-coded DNS suffix produces an invalid SNS host for China regions (for example cn-north-1 requires amazonaws.com.cn). Resolve the service endpoint from AWS region metadata instead of assuming the commercial partition suffix.

                Host = $"sns.{region}.amazonaws.com",

src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs:213

• This assumes every queue is hosted at the standard AWS endpoint. QueueAddress.FromUrl explicitly supports custom URLs such as LocalStack; those registrations currently become sqs.unknown.amazonaws.com, and China regions also require a different DNS suffix. Preserve the explicit endpoint in metadata and otherwise resolve the regional SQS endpoint from AWS metadata.

                Host = $"sqs.{region}.amazonaws.com",

src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs:14

• The PR title and description promise AsyncAPI 3.0 generation, but this generator is documented and tested as emitting 3.1.0. Either emit the advertised 3.0 document or update the PR/package-facing description to 3.1 so consumers select the correct validator and tooling.

/// Generates an AsyncAPI 3.1 document from the publications and subscriptions captured in an
/// <see cref="IMessagingMetadataRegistry"/>.

[Copilot]

Pull request overview

Copilot reviewed 55 out of 56 changed files in this pull request and generated 4 comments.

Suppressed comments (6)

src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs:213

• This SQS hostname is also wrong outside the standard AWS partition; China queue URLs use the amazonaws.com.cn suffix, and explicit queue URLs may use another host entirely. Capture/resolve the actual endpoint rather than rebuilding it as sqs.{region}.amazonaws.com.

                Host = $"sqs.{region}.amazonaws.com",

build.ps1:34

• The CI script only runs projects in $testProjects; JustSaying.CloudEvents.Tests is not listed, so the CloudEvents suite in this stacked change never executes in CI. Include it alongside the new AsyncApi suite.

    (Join-Path $solutionPath "tests" "JustSaying.AsyncApi.Tests" "JustSaying.AsyncApi.Tests.csproj"),

src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs:73

• During build-time generation the process entry assembly is JustSaying.AsyncApi.GetDocument, not the loaded application (the tool itself notes this in Program.cs:116-117). If the user leaves Title unset, the generated document is therefore titled after the tool instead of the application. Resolve the captured host's application name or pass the application assembly name into generation.

                Title = _options.Title ?? Assembly.GetEntryAssembly()?.GetName().Name ?? "JustSaying application",

src/JustSaying.AsyncApi.BuildTools/build/JustSaying.AsyncApi.BuildTools.targets:19

• The comment documents direct invocation via dotnet msbuild -t:GenerateJustSayingAsyncApiDocuments, but this target has no build dependency. On a clean checkout, TargetPath, the deps file, and the runtimeconfig have not been produced, so the documented command fails. Either make a direct-invocation wrapper build the selected target framework first or document that callers must build first.

  <Target Name="GenerateJustSayingAsyncApiDocuments"
          Inputs="$(TargetPath);$(ProjectDepsFilePath);$(ProjectRuntimeConfigFilePath)"
          Outputs="$(_JustSayingAsyncApiFileListPath)">

src/JustSaying.AsyncApi/AsyncApiDocumentGenerator.cs:203

• Hard-coding amazonaws.com produces an invalid SNS endpoint for supported non-default AWS partitions; for example arn:aws-cn:sns:cn-north-1:... is actually served under amazonaws.com.cn. Preserve the ARN partition/endpoint metadata or resolve the hostname through the AWS SDK instead of constructing it from only the region.

This issue also appears on line 213 of the same file.

                Host = $"sns.{region}.amazonaws.com",

src/JustSaying.CloudEvents/CloudEventsServiceCollectionExtensions.cs:38

• Because this uses TryAdd, a previously registered CloudEventOptions instance may differ from the local options captured by the serialization-factory lambda below. AsyncApi resolves the registered instance while the serializer uses the local one, so the documented CloudEvents type names can differ from the emitted wire values. Resolve CloudEventOptions from the service provider when constructing the factory.

        services.TryAddSingleton(options);