Metadata is descriptive information attached to an endpoint. It does not change the endpoint’s execution directly; routing, middleware, and documentation tools inspect it to add behavior or information. section 11.3
Endpoint metadata commonly supports three jobs:
- Routing metadata gives an endpoint a name, such as WithName(), for URL generation. section 11.3
- Middleware metadata lets authorization, hostname filtering, output caching, and CORS apply endpoint-specific policies. section 11.3 section 29.3.3
- OpenAPI metadata describes tags, responses, summaries, descriptions, parameters, and other endpoint details for generated documentation. section 11.3 section 11.5.1
Documenting a fruit endpoint
A minimal API can attach .WithTags("fruit"), .Produces<Fruit>(), and .ProducesProblem(404) to describe its group, success response, and error response. Adding .WithSummary(), .WithDescription(), and .WithOpenApi() extends the generated Swagger documentation. section 11.3 section 11.5.1
Listing 11.2 Adding OpenAPI metadata to improve endpoint documentation
using System.Collections.Concurrent;
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
WebApplication app = builder.Build();
var _fruit = new ConcurrentDictionary<string, Fruit>();
app.UseSwagger();
app.UseSwaggerUI();
app.MapGet("/fruit/{id}", (string id) =>
_fruit.TryGetValue(id, out var fruit)
? TypedResults.Ok(fruit)
: Results.Problem(statusCode: 404))
.WithTags("fruit") #1
.Produces<Fruit>() #2
.ProducesProblem(404); #3
app.MapPost("/fruit/{id}", (string id, Fruit fruit) =>
_fruit.TryAdd(id, fruit)
? TypedResults.Created($"/fruit/{id}", fruit)
: Results.ValidationProblem(new Dictionary<string, string[]>
{
{ "id", new[] { "A fruit with this id already exists" } }
}))
.WithTags("fruit") #4
.Produces<Fruit>(201) #5
.ProducesValidationProblem(); #6
app.Run();
record Fruit(string Name, int stock);
#1 Adding a tag groups the endpoints in Swagger UI. Each endpoint can have multiple tags.
#2 The endpoint can return a Fruit object. When not specified, a 200 response is assumed.
#3 If the id isn’t found, the endpoint returns a 404 Problem Details response.
#4 Adding a tag groups the endpoints in Swagger UI. Each endpoint can have multiple tags.
#5 This endpoint also returns a Fruit object but uses a 201 response instead of 200.
#6 If the ID already exists, it returns a 400 Problem Details response with validation errors.
Inspect a complete minimal API example that uses metadata to group endpoints and document response types and status codes. section 11.3
