OpenAPI + MinimalApis

[captainsafia]

What would you like see:

• Documentation
• Sample
• Tutorial

---

Endpoints defined via minimal APIs can be annotated with metadata for use in OpenAPI libraries with a series of extension methods.

You can set the EndpointName or EndpointGroupName of an endpoint using the WithName and WithGroupName extension methods as follows.

string SomeFoo() => "This is a string.";
app.MapGet("/foo", SomeFoo).WithName("MyEndpointName").WithGroupName("EndpointName");

Note: If you have multiple WithName statements on the same endpoint, the last endpoint will be favored.

On the topic of endpoint names, by default, endpoints that use a method group or named lambda will have their endpoint name set to the method name. For example, in the code snippet below, the endpoint will have a default endpoint name of SomeFoo.

string SomeFoo() => "This is a string.";
app.MapGet("/foo", SomeFoo);

This default endpoint name can be overloaded by using the WithName extension method as referenced above.

string SomeFoo() => "This is a string.";
app.MapGet("/foo", SomeFoo).WithName("MyOwnSpecialName");

To omit an endpoint from being displayed in API metadata, you can use the ExcludeFromDescription extension method on the endpoint.

app.MapGet("/foo", () => { .. }).ExcludeFromDescription();

OK, but let's say that you did want an endpoint to be annoted. In addition to endpoint names, you can also use the various ProducesX endpoints to indicate the response types of a method. The available extension methods are:

• Produces<TResponse>(int statusCode = 200, string? contentType = "application/json", params string[] additionalContentTypes)
• Produces(int statusCode = 200, System.Type? responseType = null, string? contentType = "application/json", params string[] additionalContentTypes)
• ProducesProblem(int statusCode, string? contentType = "application/problem+json")
• ProducesValidationProblem(int statusCode = 400, string? contentType = "application/validationproblem+json")

So, in general, the Produces extension methods give you the flexibility to set a ProblemDetails response type for your endpoint or define what response it returns on happy-path scenarios. You can do this with the generic-typed implementation Produces<TResponse> or with the Produces attribute. So, for example, to define the response metadata for a POST method that returns a Todo or a ProblemDetails response you can annotate it using the following extension methods.

app.MapPost("/todos", (Todo todo) => { ... })
    .ProducesProblem(401)
    .Produces<Todo>(201);

Note: ProducesProblem is the only extension method that doesn't set a status code by default. This allows you to make the right choices about what the most detailed status code for the scenarios in your API is, as opposed to using a generic 500 status code.

Setting request types in OpenAPIs

In addition to setting the type of data that is produced as the response in an endpoint, we can also document what data an endpoint takes as endpoint using the Accepts extension method.

For example, to document that a method accepts a Todo type in an application/json payload would be documented as follows.

app.MapPost("/todos", (Todo todo) => { ... })
    .Accepts<Todo>("application/json")
    .ProducesProblem(401)
    .Produces<Todo>(201);