AV0027: Use DescribeApiVersions

Cause

API version descriptions are resolved from the services before every API has been mapped.

Rule Description

An IApiVersionDescriptionProvider resolved from the services describes the APIs that were known when the services were built. Minimal APIs are mapped onto the application afterward, so they are not among them. Describing the versions from the application itself waits until every API has been mapped, which is why there was nothing to choose between before minimal APIs existed.

Consider the following code:

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddApiVersioning().AddApiExplorer();

var app = builder.Build();

app.MapGet( "/order", () => Results.Ok() ).HasApiVersion( 1.0 );

var descriptions = app.Services.GetRequiredService<IApiVersionDescriptionProvider>().ApiVersionDescriptions;

app.Run();

The provider was resolved from the services, so the endpoint mapped above it is not described.

How to Fix Violations

Describe the versions from the application, which waits until every API has been mapped.

var app = builder.Build();

app.MapGet( "/order", () => Results.Ok() ).HasApiVersion( 1.0 );

var descriptions = app.DescribeApiVersions();

app.Run();

When to Suppress Warnings

It is safe to suppress this rule if the descriptions are deliberately limited to the APIs known when the services were built.