dotnet / dotnet/aspnetcore

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

Open
#63,225 9 comments 5 reactions 0 assignees View on GitHub
area-minimal design-proposal feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 6h
Merged PRs (30d)
290

Description

## 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:

```csharp
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:

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.