Proposal: OpenApiOptions with Synchronous Transformer Overloads
- 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
Assessment
This issue has not been assessed yet.