API Documentation with Swagger/OpenAPI

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();  // interactive docs at /swagger

Common follow-ups: What's the difference between Swashbuckle and the newer built-in Microsoft.AspNetCore.OpenApi package?;How do you customize the generated document's title and description?

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

/// <summary>Gets a product by its ID.</summary>
/// <param name="id">The product's unique identifier.</param>
[HttpGet("{id}")]
public IActionResult GetProduct(int id) { ... }

builder.Services.AddSwaggerGen(c => {
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "MyApi.xml"));
});

Common follow-ups: What happens if XML comments are missing for some endpoints?;How do you document response types beyond just the success case?

builder.Services.AddSwaggerGen(c => {
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme {
        Type = SecuritySchemeType.Http, Scheme = "bearer", BearerFormat = "JWT"
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement {
        { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" } }, Array.Empty<string>() }
    });
});

Common follow-ups: How do you apply security requirements to only specific endpoints instead of globally?;How does this differ for API key or OAuth2 authentication schemes?

[HttpGet("{id}")]
[ProducesResponseType(typeof(ProductDto), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
public IActionResult GetProduct(int id) { ... }

// Minimal API equivalent
app.MapGet("/products/{id}", (int id) => { ... })
   .Produces<ProductDto>(200)
   .Produces(404);

Common follow-ups: What happens to a response type that's never explicitly declared with ProducesResponseType?;How does this integrate with automatic ProblemDetails generation?

builder.Services.AddOpenApi();  // built-in, .NET 9+

var app = builder.Build();
app.MapOpenApi();  // exposes /openapi/v1.json

// Pairing with a separate UI, e.g., Scalar
app.MapScalarApiReference();

Common follow-ups: What functionality does Swashbuckle still offer that the built-in package lacks?;How do you migrate an existing Swashbuckle-based project to the built-in package?

[Tags("Products")]
[HttpGet]
public IActionResult GetAll() { ... }

// Minimal API
app.MapGet("/products", () => { ... }).WithTags("Products");

builder.Services.AddSwaggerGen(c => {
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });
});

Common follow-ups: How does tag grouping interact with API versioning's own document separation?;Can you customize the order tags appear in within Swagger UI?

[ApiExplorerSettings(IgnoreApi = true)]
[HttpGet("internal/debug-info")]
public IActionResult DebugInfo() { ... }

// Minimal API equivalent
app.MapGet("/internal/debug-info", () => { ... }).ExcludeFromDescription();

Common follow-ups: What's the risk of an undocumented endpoint still being discoverable and callable by anyone?;How does this differ from actually restricting access via authorization?

public class ProductExample : IExamplesProvider<ProductDto> {
    public ProductDto GetExamples() => new() { Name = "Wireless Mouse", Price = 29.99m, Category = "Electronics" };
}

builder.Services.AddSwaggerGen(c => c.ExampleFilters());
builder.Services.AddSwaggerExamplesFromAssemblyOf<ProductExample>();

Common follow-ups: How do default auto-generated examples compare to explicitly authored ones in usefulness?;How do you provide different examples for different scenarios of the same endpoint?

# Using NSwag CLI to generate a TypeScript client
nswag openapi2tsclient /input:https://api.example.com/swagger/v1/swagger.json /output:api-client.ts

# Or a C# client
nswag openapi2csclient /input:swagger.json /output:ApiClient.cs /namespace:MyApp.Client

Common follow-ups: How do you automate client regeneration as part of a CI/CD pipeline when the API contract changes?;What's the risk of manually hand-writing HTTP client code instead?

# Using Spectral to lint an OpenAPI spec for quality/consistency issues
spectral lint https://api.example.com/swagger/v1/swagger.json

# Contract testing validates actual runtime responses match the documented schema
# as part of a CI pipeline step, failing the build on mismatch

Common follow-ups: Since Swashbuckle generates docs FROM code, how can drift still occur?;How does this differ for a hand-maintained OpenAPI spec used as a design-first contract?