Swagger for .NET - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: aspnet-core for OpenAPI documentation.

Swashbuckle Setup

// Program.cs
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "API for managing users and orders",
    });

    // XML comments
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);

    // JWT auth in Swagger UI
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Enter JWT token",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        BearerFormat = "JWT",
        Scheme = "bearer",
    });
    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer",
                }
            },
            Array.Empty<string>()
        }
    });
});

// Enable XML docs in .csproj
// <GenerateDocumentationFile>true</GenerateDocumentationFile>

Controller Annotations

/// <summary>
/// Manages user resources
/// </summary>
[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
[Tags("Users")]
public class UsersController : ControllerBase
{
    /// <summary>
    /// Get user by ID
    /// </summary>
    /// <param name="id">The user ID</param>
    /// <returns>The user details</returns>
    /// <response code="200">Returns the user</response>
    /// <response code="404">User not found</response>
    [HttpGet("{id:int}")]
    [ProducesResponseType<UserResponse>(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetById(int id) { }

    /// <summary>
    /// Create a new user
    /// </summary>
    [HttpPost]
    [ProducesResponseType<UserResponse>(StatusCodes.Status201Created)]
    [ProducesResponseType<ValidationProblemDetails>(StatusCodes.Status400BadRequest)]
    public async Task<IActionResult> Create([FromBody] CreateUserRequest request) { }
}

Operation Filters

public class AddCorrelationIdHeader : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        operation.Parameters ??= new List<OpenApiParameter>();
        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "X-Correlation-Id",
            In = ParameterLocation.Header,
            Required = false,
            Schema = new OpenApiSchema { Type = "string" },
        });
    }
}

// Register
options.OperationFilter<AddCorrelationIdHeader>();

NSwag Alternative

// Install: dotnet add package NSwag.AspNetCore
builder.Services.AddOpenApiDocument(config =>
{
    config.Title = "My API";
    config.Version = "v1";
    config.AddSecurity("Bearer", new NSwag.OpenApiSecurityScheme
    {
        Type = NSwag.OpenApiSecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
    });
});

app.UseOpenApi();
app.UseSwaggerUi();

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
No response type annotations	Incomplete docs	Use [ProducesResponseType]
Missing XML comments	No descriptions	Enable and write XML docs
Swagger in production	Security risk	Conditionally enable for dev
No auth scheme in docs	Can't test auth endpoints	Add security definition

Quick Troubleshooting

Issue	Likely Cause	Solution
No XML comments	Not enabled	Add <GenerateDocumentationFile>
Missing endpoint	Wrong route	Check [Route] attributes
Auth not working in UI	Missing security definition	Add AddSecurityDefinition
Schema conflicts	Duplicate type names	Use SchemaId configuration