Add default response for all the endpoints with Microsoft.AspNetCore.OpenApi

[marcominerva]

Hi!

I would like to add a default Error response for all the endpoints of my Minimal API:

So, I have created the following Operation Transformer:

internal class DefaultResponseOperationTransformer : IOpenApiOperationTransformer
{
    public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
    {
        var defaultResponse = new OpenApiResponse()
        {
            Description = "Error",
            Content = new Dictionary<string, OpenApiMediaType>
            {
                [MediaTypeNames.Application.ProblemJson] = new()
                {
                    Schema = new()
                    {
                        Reference = new()
                        {
                            Id = nameof(ProblemDetails),
                            Type = ReferenceType.Schema
                        }
                    }
                }
            }
        };

        operation.Responses.TryAdd("default", defaultResponse);
        return Task.CompletedTask;
    }
}

This works only if I have at least one endpoint that produces a Problem response, so that the ProblemDetails schema is inserted in OpenAPI definition:

app.MapPost("/api/pople", () =>
{
    // ...
})
.ProducesProblem(StatusCodes.Status400BadRequest);

To avoid this requirement, with Swashbuckle I had defined a document filter to automatically add the corresponding schema:

internal class ProblemDetailsDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        => context.SchemaGenerator.GenerateSchema(typeof(ProblemDetails), context.SchemaRepository);
}

But this is no longer possible with Microsoft.AspNetCore.OpenApi. So, in this case what is the correct solution?

[martincostello]

I'm not aware of a way to push an entirely new schema into the document as-is.

Maybe if you defined the schema inline (not as reference, because it will be pointing at something not defined) the later bits of the pipeline will notice it's re-used in multiple places and hoist it up to be a schema reference for you?

If that doesn't work, wrap all the operations in a group and define the default error like with ProducesProblem() there so it gets applied to all endpoints?

[marcominerva]

@captainsafia thank you for your support! I have created a small repro to showcase the issue: https://github.com/marcominerva/DefaultResponseTransformer

[captainsafia]

@marcominerva Eep -- this is my fault. Setting the schema ID isn't sufficient since those get processed by the OpenApiSchemaStore which is an internal API.

I tried this approach to get the desired result by inserting the schema via a document generator. What do you think about this?

[marcominerva]

@captainsafia Yes, your approach correctly defines and reuses the ProblemDetails schema, thanks. But, unfortunately, there is a last issue. If I have an endpoint that already defines a Problem response, for example:

app.MapGet("/api/ping", () =>
{
    return TypedResults.Ok();
})
.ProducesProblem(StatusCodes.Status400BadRequest);

And then I use also your Transformers, because I still want the default response, I get an exception:

Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware[1]
      An unhandled exception has occurred while executing the request.
      System.ArgumentException: An item with the same key has already been added. Key: ProblemDetails
         at System.Collections.Generic.Dictionary`2.TryInsert(TKey key, TValue value, InsertionBehavior behavior)
         at System.Collections.Generic.Dictionary`2.Add(TKey key, TValue value)
         at Microsoft.AspNetCore.OpenApi.OpenApiSchemaReferenceTransformer.TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
         at Microsoft.AspNetCore.OpenApi.OpenApiDocumentService.ApplyTransformersAsync(OpenApiDocument document, IServiceProvider scopedServiceProvider, CancellationToken cancellationToken)
         at Microsoft.AspNetCore.OpenApi.OpenApiDocumentService.GetOpenApiDocumentAsync(IServiceProvider scopedServiceProvider, CancellationToken cancellationToken)
         at Microsoft.AspNetCore.OpenApi.OpenApiDocumentService.GetOpenApiDocumentAsync(IServiceProvider scopedServiceProvider, CancellationToken cancellationToken)
         at Microsoft.AspNetCore.Builder.OpenApiEndpointRouteBuilderExtensions.<>c__DisplayClass0_0.<<MapOpenApi>b__0>d.MoveNext()

I see that in your code you use the document.Components.Schemas.TryAdd method, but when it is executed, the Schema collection is still empty, so it always adds the schema before the default implementation.

[UltraWelfare]

@marcominerva Eep -- this is my fault. Setting the schema ID isn't sufficient since those get processed by the OpenApiSchemaStore which is an internal API.

I tried this approach to get the desired result by inserting the schema via a document generator. What do you think about this?

I've tried it and it seems to work (apart from @marcominerva's problem) but I wonder if there's a way to get the schema without manually typing it.

I have the same use-case of wanting to add a "400" response to all endpoints, however the class that I return also contains an enum.. I'm not sure how to go ahead and type this on TransformAsync of DefaultResponseDocumentTransformer.

[marcominerva]

@captainsafia I have managed to solve the duplication problem by explicitly checking if there already is an endpoint that returns a ProblemDetails response, so I add it to the schemas collection only if does not exist:

app.MapGet("/api/ping", () =>
{
    return TypedResults.Ok();
})
.ProducesProblem(StatusCodes.Status400BadRequest);

public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
    // Checks if the ProblemDetails type is already defined in the document (because there is at least one endpoint that returns it).
    var isProblemDetailsSchemaDefined = context.DescriptionGroups
       .SelectMany(g => g.Items).SelectMany(i => i.SupportedResponseTypes)
       .Any(type => type.Type == typeof(ProblemDetails));

    if (isProblemDetailsSchemaDefined)
    {
        return Task.CompletedTask;
    }

    document.Components ??= new();
    document.Components.Schemas.TryAdd(nameof(ProblemDetails), new OpenApiSchema
    {

I have updated my sample at https://github.com/marcominerva/DefaultResponseTransformer with this workaround.