AV0031: Missing API explorer

Cause

An OpenAPI document is generated without the API explorer that describes the APIs it is generated for.

Rule Description

An OpenAPI document is generated from what the API explorer discovered, and what it discovers depends on how the APIs were built. OData and gRPC are each described by an explorer of their own, which nothing else registers on their behalf.

Consider the following code:

var builder = WebApplication.CreateBuilder( args );

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

Nothing describes the APIs, so the generated documents are empty.

An application that versions OData or gRPC needs the matching explorer as well:

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

An API built any other way is described by the explorer the rest of them build on, so a specialized explorer on its own satisfies the rule for the APIs it specializes in.

How to Fix Violations

Add the API explorer that matches how the APIs were built.

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

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

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

When to Suppress Warnings

It is safe to suppress this rule if the API explorer is registered outside the compilation, such as by a referenced library that configures the services on the application’s behalf.