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]

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?

@captainsafia could you tell me if Microsoft.AspNetCore.OpenApi contains such a logic to identify that the same schema is re-used multiple times?

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?

If the above approach does not work, I think this could be a viable solution.

[captainsafia]

#58719

Yes, it does. You'll want to create the OpenApiSchema in your transformer. You'll also want to set the x-schema-id property in OpenApiSchema.Annotations to set the reference ID that should be used for it.

Also, I think what you've proposed here is covered by the issue that @mikekistler opened over in #58719.

It encapsulates updating the ApiExplorer layer to sets these error responses as the default response so that all consumer of it can use them and you don't have to rely on transformers and filters to do it. If that sounds interesting to you, go ahead and give the issue an upvote.