--- name: swagger-dotnet description: | Swashbuckle and NSwag for ASP.NET Core API documentation. Covers XML comments, operation filters, and OpenAPI customization. USE WHEN: user mentions "Swagger", "Swashbuckle", "NSwag", ".NET OpenAPI", "API documentation", "Swagger UI", ".NET API docs" DO NOT USE FOR: Springdoc OpenAPI - use `springdoc-openapi`, generic OpenAPI spec - use `openapi` allowed-tools: Read, Grep, Glob, Write, Edit --- # Swagger for .NET - Quick Reference > **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `aspnet-core` for OpenAPI documentation. ## Swashbuckle Setup ```csharp // 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() } }); }); // Enable XML docs in .csproj // true ``` ## Controller Annotations ```csharp /// /// Manages user resources /// [ApiController] [Route("api/[controller]")] [Produces("application/json")] [Tags("Users")] public class UsersController : ControllerBase { /// /// Get user by ID /// /// The user ID /// The user details /// Returns the user /// User not found [HttpGet("{id:int}")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status404NotFound)] public async Task GetById(int id) { } /// /// Create a new user /// [HttpPost] [ProducesResponseType(StatusCodes.Status201Created)] [ProducesResponseType(StatusCodes.Status400BadRequest)] public async Task Create([FromBody] CreateUserRequest request) { } } ``` ## Operation Filters ```csharp public class AddCorrelationIdHeader : IOperationFilter { public void Apply(OpenApiOperation operation, OperationFilterContext context) { operation.Parameters ??= new List(); operation.Parameters.Add(new OpenApiParameter { Name = "X-Correlation-Id", In = ParameterLocation.Header, Required = false, Schema = new OpenApiSchema { Type = "string" }, }); } } // Register options.OperationFilter(); ``` ## NSwag Alternative ```csharp // 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 `` | | 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 |