AV0025: Missing OpenAPI document description

Cause

An OpenAPI document is generated without the description that documents it.

Rule Description

What an OpenAPI document says about itself is taken from the assembly it is generated for. The title is supplied by the project whether it was asked for or not, but the description is only there if it was stated.

Consider the following code:

var builder = WebApplication.CreateBuilder( args );

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

Nothing in the project describes what the generated document is for, so the description of every document is left empty.

The description is taken from the assembly the application was started from, so this is only reported for a project that produces an application. A library configuring OpenAPI on an application’s behalf has nothing to give and is not reported.

How to Fix Violations

Set Description in the project file.

<PropertyGroup>
  <Description>Order management APIs.</Description>
</PropertyGroup>

The attribute the project generates from that property can also be written by hand:

[assembly: AssemblyDescription( "Order management APIs." )]

When to Suppress Warnings

It is safe to suppress this rule if the generated documents are not published, or if the description is supplied when the document is transformed rather than by the assembly.