dotnet / dotnet/aspnetcore

Proposal: OpenApiOptions with Synchronous Transformer Overloads

Open
#60,943 0 comments 0 reactions 0 assignees View on GitHub
api-suggestion area-mvc feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 5h
Merged PRs (30d)
276

Description

## Background and Motivation

Since the release of .NET 9 and the new `Microsoft.AspNetCore.OpenApi` document generator, I have written and seen numerous transformers for `OpenApiOperation` and `OpenApiDocument`. In most instances, the implementation of these transformers has been synchronous, requiring the return of `Task.CompletedTask`. I believe it would enhance the developer experience if the package provided an `Action<>` overload for each transformer, eliminating the need to return a completed task for synchronous scenarios.

## Proposed API

```diff
namespace Microsoft.AspNetCore.OpenApi;

public sealed class OpenApiOptions
{
+ public OpenApiOptions AddDocumentTransformer(Action transformer);

+ public OpenApiOptions AddOperationTransformer(Action transformer);

+ public OpenApiOptions AddSchemaTransformer(Action transformer)
}
```

## Usage Examples

**Before:**
```csharp
options.AddDocumentTransformer((document, context, _) =>
{
var descriptionProvider = context.ApplicationServices.GetRequiredService();
var versionDescription = descriptionProvider.ApiVersionDescriptions.FirstOrDefault(x => x.GroupName == version);
document.Info.Version = versionDescription?.ApiVersion.ToString();
return Task.CompletedTask;
});
```

**After:**
```csharp
options.AddDocumentTransformer((document, context) =>
{
var descriptionProvider = context.ApplicationServices.GetRequiredService();
var versionDescription = descriptionProvider.ApiVersionDescriptions.FirstOrDefault(x => x.GroupName == version);
document.Info.Version = versionDescription?.ApiVersion.ToString();
});
```

## Alternative Designs

There are not many alternative designs to consider. One alternative could be to leave everything as it is.

## Risks

The only potential risk is that there could be a conflict if developers have already created custom overloads or extensions.

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.