API proposal: Allow OpenAPI registration to resolve document names upon request

[Youssef1313]

Background and Motivation

See #66408. This proposal serves as an alternative.

In short, today, OpenAPI requires document names to be known at the time when the services are registered. There can be scenarios (e.g, Asp.Versioning) when the document names are not known that early.

Proposed API

1. Add IAdditionalOpenApiDocumentNameProvider:

   + namespace Microsoft.AspNetCore.OpenApi.Extensions;
   +
   + /// <summary>
   + /// An interface that lets users provide additional OpenAPI document names.
   + /// </summary>
   + public interface IAdditionalOpenApiDocumentNameProvider
   + {
   +     /// <summary>
   +     /// Gets the additional document names.
   +     /// </summary>
   +     public IEnumerable<string> DocumentNames { get; }
   + }

2. Make documentName in AddOpenApi nullable.

   namespace Microsoft.Extensions.DependencyInjection;
   
   public static class OpenApiServiceCollectionExtensions
   {
   -    public static IServiceCollection AddOpenApi(this IServiceCollection services, string documentName)
   +    public static IServiceCollection AddOpenApi(this IServiceCollection services, string? documentName)
   }

Exact changes:

• All keyed OpenAPI services will be registered using KeyedService.AnyKey. This allows document names that are not known during the time of building services to still work as expected.
• If AddOpenApi is called with null document name, we won't register NamedService<OpenApiDocumentService> (the whole purpose of this service is to get the registered document names later - at this point, we don't even have any document name)
• If AddOpenApi is called with a non-null document name, we register NamedService<OpenApiDocumentService>.
• The only AddOpenApi overload that can accept a null documentName is the simple overload that doesn't configure OpenApiOptions. The OpenApiOptions is per-document and cannot work with a null document name. In future, if we ever needed to have some "global" options that applies to all documents in this mode, that can probably be its own simplified options class.
• Whenever we want to know the valid document names, we combine that information from two sources:
  • The new interface, if registered.
  • The internal NamedService<OpenApiDocumentService> which is used when AddOpenApi is given a non-null document name.

Usage Examples

See current prototype in dotnet/aspnet-api-versioning#1186 (dotnet/aspnet-api-versioning@5005039). In short:

services.AddSingleton<IAdditionalOpenApiDocumentNameProvider, OpenApiVersionedDocumentNamesProvider>();
services.AddOpenApi(documentName: null);

Then OpenApiVersionedDocumentNamesProvider is responsible for providing the additional document names.

Important

Our XmlCommentGenerator intercepts the AddOpenApi call that doesn't accept options and forwards it to something like the following:

services.AddOpenApi(documentName, options =>
{
    options.AddSchemaTransformer(new XmlCommentSchemaTransformer());
    options.AddOperationTransformer(new XmlCommentOperationTransformer());
});

Because our current OpenApiOptions is per-document, the above cannot work for AddOpenApi(documentName: null).
The source generated code can then be updated to throw NotSupportedException for null document names.

Alternative Designs

We should consider if we should take this a step further. As currently proposed and implemented in prototype, the public IAdditionalOpenApiDocumentNameProvider only really provides the additional document names, as the name suggests.

We still have an internal IDocumentProvider interface. One of its responsibilities is to provide the document names, and its implementation is updated to "combine" all the document names (ones added explicitly through AddOpenApi and the additional ones provided externally via the new interface)

What we can consider is, if the public interface should simply be responsible of providing all the document names. This might also help us clean all the reflection logic for build-time generation. If we want to do so, we need to have a concrete API shape for this.

Risks

[github-actions]

Triage Summary

Area: area-minimal — This issue proposes changes to Microsoft.AspNetCore.OpenAPI and AddOpenApi(), which falls under the Minimal APIs / OpenAPI area.
Type: api-proposal — This is a formal API addition proposal with a concrete API shape, usage examples, and alternative design discussion.

Potential Duplicates

• API Proposal: Microsoft.AspNetCore.OpenAPI Not Extensible Due To Internal Types #66408 - "API Proposal: Microsoft.AspNetCore.OpenAPI Not Extensible Due To Internal Types" (similarity: related — same underlying scenario of making OpenAPI work with ASP.NET API Versioning, but this issue proposes a different, alternative API shape via IAdditionalOpenApiDocumentNameProvider and a nullable documentName overload, rather than making internal types public)

Notes

• This proposal is explicitly described as an alternative to API Proposal: Microsoft.AspNetCore.OpenAPI Not Extensible Due To Internal Types #66408. Both address the same root problem (OpenAPI document names not known at service registration time), but with different approaches. The team should evaluate the two proposals together.
• The prototype implementation is available at No Reflection aspnet-api-versioning#1186 for review.

Generated by Issue Triage Agent for dotnet/aspnetcore for issue #66725 · ● 1.9M · ◷

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.