AV0021: Use the versioned API explorer

Cause

An application versions its APIs but describes them with an API explorer that is unaware of API versions.

Rule Description

AddEndpointsApiExplorer() describes endpoints without their versions. Once API versioning is in use, the generated documentation shows a single, version-less view of an API that actually has more than one version.

Consider the following code:

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddApiVersioning();

API versioning is configured, but nothing was told to describe the versions.

How to Fix Violations

Replace the call with the versioned API explorer, which adds the endpoints API explorer itself.

var builder = WebApplication.CreateBuilder( args );

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

An application using OData, gRPC, and/or OpenAPI calls the corresponding variant instead:

builder.Services.AddApiVersioning()
                .AddOData()
                .AddODataApiExplorer()
                .AddOpenApi();

builder.Services.AddApiVersioning()
                .AddGrpc()
                .AddGrpcApiExplorer()
                .AddOpenApi();

See API explorer options for what the versioned explorer can be configured to describe.

When to Suppress Warnings

It is safe to suppress this rule if the documentation is deliberately generated without API versions.