Idea: Improvements to Default OpenAPI Descriptions

[austins]

1. Produces 200 is always set. This is a reasonable default; however, how can we handle cases where the endpoint may only return, for example, just a 201? The Swagger doc will output a 200 where that endpoint doesn't return that. Describe() with clearDefaults=true would require you to have to describe everything again, not just the sucessful response(s), and potentially missing other defaults for an endpoint.

2. Since endpoints are authorized by default, would it be good to add in a default for 401? AnonymousVerbs is empty unless AllowAnonymous is set for any verb. On an aside, I believe there isn't a way yet to set Produces for different verbs, but for now, here's an example:

if (Definition.AnonymousVerbs?.Any() != true)
{
    b.Produces(401);
}

What are your thoughts?

[dj-nitehawk]

implemented in 5.8.1.11-beta

public override void Configure()
{
    //lack of AllowAnonymous() will auto add 401 produces meta
    Roles("test"); //any Roles/Claims/Permissions will auto add 403 produces meta
    Description(x => x
        .ClearDefaultProduces(200, 401, 403) //user has the choice which default produces to clear
        .Produces<Response>(201, "application/json"));
}

mind the small breaking change in this beta build: https://github.com/FastEndpoints/FastEndpoints/blob/main/Src/Library/changelog.md#breaking-changes

[austins]

Works brilliantly. Thanks!

[austins]

@dj-nitehawk Curious about adding on one more case, what do you think?

When ErrorOptions.ProducesMetadataType is set, it checks if there is a validator and sets the 400 response:

FastEndpoints/Src/Library/Endpoint/Endpoint.Setup.cs

Line 433 in 0dfb728

if (opts.ProducesMetadataType is not null && Definition.ValidatorType is not null)

Would it be good to set ProducesMetadataType = typeof(HttpValidationProblemDetails) by default and add default 400 produces if Definition.ThrowIfValidationFails == true? To me, it would seem good since that's what the validation failure is returned as.

            var opts = FastEndpoints.Config.ErrOpts;
            if (opts.ProducesMetadataType is not null && Definition.ValidatorType is not null && Definition.ThrowIfValidationFails)
                b.Produces(opts.StatusCode, opts.ProducesMetadataType, "application/problem+json");

[dj-nitehawk]

done in 5.8.1.13-beta

however, FastEndpoints.ProblemDetails class is not the default.
FastEndpoints.ErrorResponse is.

if you want to make ProblemDetails the default you'd have to do this to change the default:

app.UseFastEndpoints(config =>
{
    config.Errors.UseProblemDetails();
});

[austins]

You're right, Just tried the changes out. It works good so far. Thanks again! 💯