API Proposal: Microsoft.AspNetCore.OpenAPI Not Extensible Due To Internal Types

[commonsensesoftware]

Background and Motivation

The Microsoft.AspNetCore.OpenAPI library provides a number of useful extensions for generating OpenAPI documents, but it does not work well with ASP.NET API Versioning out-of-the-box. ASP.NET API Versioning has provided a new library to bridge the gaps, but it is forced to use unwieldly Reflection techniques to make things work because all of the necessary extension points in Microsoft.AspNetCore.OpenAPI are internal.

While the Reflection workaround is a short-term fix, it is significantly slower, complicates or breaks the AOT story, and places the extensions at future risk of non-visible changes that may only trigger runtime failures. All of these reflect negatively upon developer and customer experience.

These changes are requested to be part of a .NET 10 servicing release. .NET 11 and beyond should consider an alternate design.

Proposed API

using System.ComponentModel;

namespace Microsoft.AspNetCore.OpenApi;

+ [EditorBrowsable(EditorBrowsableState.Never)]
- internal sealed class OpenApiSchemaService( /* ... */ )
+ public sealed class OpenApiSchemaService( /* ... */ )
  {
  }

+ [EditorBrowsable(EditorBrowsableState.Never)]
- internal interface IDocumentProvider
+ public interface IDocumentProvider
  {
  }

+ [EditorBrowsable(EditorBrowsableState.Never)]
- internal sealed class NamedService<TService>(string name)
+ public sealed class NamedService<TService>(string name)
  {
  }

+ [EditorBrowsable(EditorBrowsableState.Never)]
- internal sealed class OpenApiDocumentProvider(IServiceProvider serviceProvider) : IDocumentProvider
+ public sealed class OpenApiDocumentProvider(IServiceProvider serviceProvider) : IDocumentProvider
  {
  }

+ [EditorBrowsable(EditorBrowsableState.Never)]
- internal sealed class OpenApiDocumentService( /* .. */ ) : IOpenApiDocumentProvider
+ public sealed class OpenApiDocumentService( /* .. */ ) : IOpenApiDocumentProvider
  {
-     public async Task<OpenApiDocument> GetOpenApiDocumentAsync( /* .. */ )
+     internal async Task<OpenApiDocument> GetOpenApiDocumentAsync( /* .. */ )
      {
      }
  }

  public sealed class OpenApiOptions
  {
-    public string DocumentName { get; internal set; } = OpenApiConstants.DefaultDocumentName;        
+    public string DocumentName
+    {
+        get => field ?? OpenApiConstants.DefaultDocumentName;
+
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        set;
+    }
  }

The changes in this commit, which is a fork of the library, demonstrate the required changes. If this were accepted, the changes can be submitted as a pull request.

Usage Examples

The changes in this commit demonstrate how API Versioning would use these changes and supplant the need to use Reflection.

The necessary changes were privately built and consumed by API Versioning to confirm the proposed changes will indeed work if they are approved and released.

Alternative Designs

There is a potential alternate design that would take the existing design limitations into consideration, but this would require significantly more time and effort. A refactored, alternate design should be tracked in a separate issue and considered for a future major release in .NET 11 or beyond.

Risks

• internal types are now public; however, risk is minimized by:
  • Only the type and constructor are public; all other members remain or become internal
  • The [EditorBrowsable(EditorBrowsableState.Never)] can be applied to reduce their accidental discovery
• IDocumentProvider is a magical internal interface that is matched only by type name
  • This interface has to become public is it can be mapped by dependency injection
  • There may be some other combination or design that limits unintended usage

[github-actions]

Triage Summary

Area: area-minimal — The issue is about Microsoft.AspNetCore.OpenAPI, which lives under src/OpenApi/ and is scoped to OpenAPI document generation for minimal APIs.

Type: api-proposal — The issue follows the formal API proposal template (Background & Motivation, Proposed API diff, Usage Examples, Alternative Designs, Risks) and requests specific type visibility changes to Microsoft.AspNetCore.OpenAPI to enable third-party extensibility without reflection.

Potential Duplicates

• None found — searches for related OpenAPI extensibility / internal-type issues returned no prior open issues describing the same request.

Notes

• The issue already carries api-suggestion and NativeAOT labels, which are consistent with the content (the reflection workaround breaks AOT).
• The proposal targets .NET 10 servicing; the author explicitly requests a separate issue for a deeper redesign in .NET 11+.
• The IDocumentProvider visibility concern (it is matched by type name via DI) may warrant additional design discussion around unintended implementations.

Generated by Issue Triage Agent for dotnet/aspnetcore for issue #66408 · ● 250.7K · ◷

[xavierjohn]

+1 for this proposal. A few key reasons:

1. Reflection is not a sustainable workaround — API Versioning is a widely-used, officially-maintained
   library under dotnet/. Forcing it to use reflection against internal types is fragile, slower, and breaks
   silently on updates.
2. AOT compatibility matters now, not later — .NET 10 is pushing hard on AOT. Reflection-based workarounds
   directly undermine that story. Waiting for .NET 11 means an entire major release cycle where API Versioning

• OpenAPI + AOT is broken or degraded.

3. The risk is well-contained — Only type visibility changes; all members stay internal.
   [EditorBrowsable(Never)] discourages casual usage. The practical blast radius is minimal — these types are
   DI plumbing, not user-facing APIs.
4. Pragmatism over purity — Yes, a cleaner extensibility model in .NET 11 would be ideal. But shipping a
   working, interoperable solution now serves the developers who need versioned OpenAPI documents today.
   Perfect shouldn't be the enemy of good.
5. The alternative is worse — Without this, customers either accept broken AOT, depend on fragile
   reflection hacks, or avoid combining API Versioning with the official OpenAPI library altogether. None of
   those outcomes reflect well on the platform.
6. Proven changes — The proposal includes a working fork and a consuming commit demonstrating the changes
   work end-to-end. This isn't speculative — it's validated.

The ask is modest, the need is real, and the risk is low. Ship it in .NET 10 servicing, then design a proper
extensibility model for .NET 11.

[ScarletKuro]

While the Reflection workaround is a short-term fix, it is significantly slower, complicates or breaks the AOT story

Regarding the speed and AOT, you could use the UnsafeAccessor + UnsafeAccessorType since you are targeting only .net10 tfm. The speed is almost like accessing it directly, it's also AOT friendly. The only problem is that it can silently break if MSFT changes something.