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