0Pricing
C# Academy · Lesson

Documenting Versioned APIs

Expose docs for multiple API versions.

One Document per Version

When an API has several versions, you typically want a separate OpenAPI document for each version so consumers see only the endpoints relevant to them.

// /openapi/v1.json -> only v1 endpoints
// /openapi/v2.json -> only v2 endpoints

The API Version Description Provider

Asp.Versioning exposes IApiVersionDescriptionProvider, which lists every discovered API version. You loop over it to register a document per version.

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

foreach (var desc in provider.ApiVersionDescriptions)
{
    // desc.GroupName is e.g. "v1", "v2"
}

All lessons in this course

  1. API Versioning Strategies
  2. Configuring Asp.Versioning
  3. Generating OpenAPI Documents
  4. Documenting Versioned APIs
← Back to C# Academy