Add No-Op method/extension to OpenApiOptions for interception in inheriting APIs

[TheXenocide]

Summary

Microsoft.AspNetCore.OpenApi.SourceGenerators uses an interceptor on the AddOpenApi extension method which is only applicable to projects which define their own document generation behavior. Projects which leverage reusable behaviors to establish consistent features across many APIs need a means to allow multiple downstream consumers to append interceptor/generators.

Motivation and goals

Our organization has many solutions and APIs which share common infrastructure/behavior like Auth configuration, caching behaviors, route mapping, shared middleware, Open API doc generation, Swagger UI, etc. We do this via inheritable types and composite extension methods so that we don't have the same exact copy/paste code in a ton of APIs but as a consequence it appears that XML comment -> Open API metadata source generators are not functioning as expected in our projects. Rather than making us rewrite our shared infrastructure in a way that requires duplication or implementing source generators of our own just to leverage this feature it would be ideal if OpenApiOptions could be extended via a no-op method (or extension method) that can be intercepted in addition to the IServiceCollection extension methods to serve as an alternative interception point for the provided source generators.

In scope

One extra interception location or generated extension method for generated Open API metadata methods to integrate with.

Ideally the documentation would also make it more clear what the behavior of these generators is as figuring out what went wrong between POC and implementation was a rather involved process.

Out of scope

Guiding customers to write their own source generators or requiring them to break intentionally composited behavior into a bunch of separate order-specific/sensitive public extensions.

Risks / unknowns

I'm not currently aware of significant risks involved with this approach.

Examples

The goal is to provide a slightly more abstract integration point than just the AddOpenApi(this IServiceCollection ...) extensions to be used by organizations with large/complex shared infrastructure. Something like:

protected override void ConfigureOpenApiDocument(OpenApiOptions options)
{
    base.ConfigureOpenApiDocument(options);

    options.AddGeneratedTransformers();

    // other Solution/Project/API-specific configurations here
}

Or for more extension method chain composition-based implementations:

hostBuilder.UseSharedApiBehaviors(configureOpenApi: options => {
    options.AddGeneratedTransformers();
});

[TheXenocide]

It occurs to me that component libraries may also be able to leverage this in their own extensions to enable generated Open API metadata in libraries/packages rather than requiring every downstream consumer to regenerate the same code via AdditionalFiles

[TheXenocide]

Cleaning up some tabs and wanted to note that I did eventually find some quality documentation on the hows and wheres of interception. Perhaps I missed it the first time or perhaps there's a better way to link to it for those troubleshooting, but I wanted to note that @captainsafia did, in fact, provide good details that would have helped me figure this out without necessarily resorting to decompiling my assemblies to see the differences so my comment about documentation may have been too hasty.

[TheXenocide]

Am I correct in assuming that this issue being placed in the Backlog means that we will have to rewrite all of our APIs to manually wire up their Open API docs with the same copy paste code across many APIs if we want to continue providing documentation in our Open API specs?

We have a dynamically extensible integration API that discovers and loads assemblies which contain new controllers from assemblies that have their own DI behaviors in something like an IHostingStartup type; while awaiting this issue's completion, how does Microsoft suggest we allow those extensions to ensure their XML documentation comments are part of the Open API spec it generates? I ask because this schema is parsed at runtime and used to update APIM policies with new routes/their docs and these are now lacking the documentation they had before this upgrade.

I see there's another issue which would benefit from this solution as well. Is there no chance of getting one more interceptor/extension method before this release? bats eyelashes Pretty please? 😅

[desjoerd]

Maybe you can provide the additional files for xml comments with MSBuild props as part of your common package library.

I also don't like this interceptor being the only option at the moment.

I've got some ideas to allow for more customization around the default transformations which are happening and will write some Api proposals for that. Also related to Schema Reference Transformers. But that would be .NET 11 looking at the process of getting new apis in.

[TheXenocide]

That might work for the first project I ran into the issue with (a test harness very early in our build chain) but it certainly won't work for our dynamic runtime extensibility use cases (our software is customizable by individual customers who may add assemblies with new routes to the application post-compilation). Those dynamic extensions do have a chance to configure the DI container on startup and we could expand that behavior if necessary, which would make it possible for them to leverage the source generators in their own assemblies, but only if we have another entry mechanism for interception/generation.

[TheXenocide]

Hey @captainsafia I know time is tight on the .NET 10 release, but if we were willing to submit a PR for one more extension method and interception, is there any chance that it gets accepted into .NET 10 or do we need to start evaluating rolling back our migration to MS-provided Open API for another 2 years? We really want to move to the MS-provided tooling for this and it really could be a total show stopper on work we've already mostly implemented. If possible, how soon would you need it by?

Just to put out there part of the reason we're passionate about adopting the MS implementation here is that its release cycle is tightly coupled with .NET platform upgrades. We have been working to closer align our releases with .NET LTS releases, but we always encounter runtime-specific migration pains when first adopting new .NET versions when using third party solutions for spec generation (most recently NSwag, which requires adjustments for every new runtime and always lags the previews; they just released .NET 10 support 2 weeks ago and we've been working on migration since preview 1). Since all of our API clients and integrations are very intentionally generated off of both compile-time and runtime generated specs, this completely halts all upgrade/migration activity until we work around whatever issues exist in NSwag prior to their formal release (I believe we've even submitted PRs and had to build off of other people's PR contributions waiting for them to be integrated into the codebase for months; our .NET 8 update ended up having to go out the door with our own locally built copies of the it with patches like that compiled in). No offense to the folks over working on NSwag as they've been instrumental to our road to here and now, and we can appreciate the value of trying to contribute to the open source landscape, but we have a hard enough time maintaining our own code and other people's codebase and schedules are outside of our control, so this regularly recurring expense has been difficult for us. Since this functionality is fundamental to building Web APIs (in our shop, at least) we would really prefer the first-party MS solution tied to the platform releases.

Our codebase is very large and slow to change and our customers develop on top of it (often taking over a year to implement upgrades due to the business-critical nature of the data we handle). With the .NET release timelines and support lifecycles, we need to release a .NET platform upgrade with every LTS release ASAP so that our customers have any hope of being on a supported .NET platform before the previous LTS is abandoned. I really want to make the case of regularly adopting new .NET previews (even for non-LTS) as soon as possible to get earlier breaking change feedback and be more aligned with modern practices but this one issue has a huge chance of being a complete obstruction to that conversation for another 2 years.

Please O-API Doc Specobi, you're our only hope!

[TheXenocide]

Alas, I'll take that as a "no chance"

Do we have the option of using the legacy behavior for now since we're unable to use the source generators from our dynamic libraries?