AV0030: Missing WithDocumentPerVersion

Cause

The endpoint serving OpenAPI documents was not told to serve one per API version.

Rule Description

The endpoint serving the documents resolves them from the services of the request it is answering, which is only where the versioned documents are to be found once the endpoint has been told to look there. Without that, the endpoint serves the single, version-less document it would have served before API versioning was configured.

Consider the following code:

var builder = WebApplication.CreateBuilder( args );

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

var app = builder.Build();

app.MapOpenApi();

app.Run();

The versioned documents are generated but never served.

How to Fix Violations

Continue the expression that mapped the endpoint with WithDocumentPerVersion().

var app = builder.Build();

app.MapOpenApi().WithDocumentPerVersion();

app.Run();

When to Suppress Warnings

It is safe to suppress this rule if a single document describing every API version is intended.