All 15 API Documentation with Swagger/OpenAPI questions
More in API Documentation with Swagger/OpenAPI
How do you document multiple response types (like 200, 400, 404) for a single endpoint in Swagger using ProducesResponseType? How do you organize and group endpoints in Swagger UI by tags or API version? How do you customize example values shown in Swagger UI for request and response bodies? How do you validate that an API's actual behavior matches its published OpenAPI specification, preventing documentation drift? How do you add global metadata (like a description, contact info, and license) to the top level of a generated OpenAPI document? How do you document authentication requirements (like a JWT bearer token) in Swagger UI so users can test authenticated endpoints interactively? How does the newer built-in Microsoft.AspNetCore.OpenApi package (introduced in .NET 9) differ from the third-party Swashbuckle package? How would you exclude specific endpoints or entire controllers from appearing in the generated Swagger documentation? How would you generate a client SDK automatically from an ASP.NET Core API's OpenAPI specification? What is 'design-first' versus 'code-first' API development, and how does OpenAPI tooling support each approach?
Advertisement
ASP.NET Core › API Documentation with Swagger/OpenAPI

How do you version your OpenAPI documentation to reflect API versioning implemented via the Asp.Versioning library?

Intermediate

Answer

Swashbuckle integrates with Asp.Versioning by generating a separate SwaggerDoc per registered API version (using IApiVersionDescriptionProvider to discover them dynamically), and configuring SwaggerUI with a corresponding SwaggerEndpoint per version, producing a dropdown in the UI letting consumers browse documentation specific to each API version rather than one merged, potentially confusing document mixing all versions together.
builder.Services.ConfigureOptions<ConfigureSwaggerOptions>();  // discovers versions dynamically

app.UseSwaggerUI(options => {
    foreach (var description in app.DescribeApiVersions()) {
        options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
    }
});
Real-world example An API supporting both v1 and v2 shows a version selector dropdown in Swagger UI, letting a developer integrating against the legacy v1 contract view accurate, version-specific documentation without seeing v2-only endpoints mixed in.

Common follow-ups: How does ConfigureSwaggerOptions dynamically discover registered API versions?;What happens to a deprecated version's documentation once it's fully removed from the API?

API Versioning;Controllers vs Minimal APIs
All 15 API Documentation with Swagger/OpenAPI questions