A practical implementation guide for leveraging Swagger/OpenAPI documentation in ASP.NET Core projects, featuring advanced configurations and security integration.

Core Implementation

1. Package Installation

Install-Package Swashbuckle.AspNetCore

2. Basic Configuration

// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1.0.0",
            Title = "API Documentation",
            Description = "Core application endpoints"
        });
    });
}

public void Configure(IApplicationBuilder app)
{
    app.UseSwagger();
    app.UseSwaggerUI(c => 
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1");
    });
}

Advanced Features

1. API Version Grouping

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "User Management", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "Order Processing", Version = "v2" });
});

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "User API");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "Order API");
});

Endpoint Grouping: Apply [ApiExplorerSettings(GroupName = "v1")] attribute to controllers/actions

2. XML Documentation

<!-- Project file -->
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

services.AddSwaggerGen(c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

3. JWT Authentication Integration

Install-Package Swashbuckle.AspNetCore.Filters

services.AddSwaggerGen(c =>
{
    var securityScheme = new OpenApiSecurityScheme
    {
        Name = "JWT Authentication",
        Description = "Enter JWT Bearer token **_only_**",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        Reference = new OpenApiReference
        {
            Id = JwtBearerDefaults.AuthenticationScheme,
            Type = ReferenceType.SecurityScheme
        }
    };

    c.AddSecurityDefinition(securityScheme.Reference.Id, securityScheme);
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {securityScheme, Array.Empty<string>()}
    });

    c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
});

Customization Techniques

1. UI Customization

app.UseSwaggerUI(c =>
{
    c.DocumentTitle = "API Explorer";
    c.InjectStylesheet("/swagger-ui/custom.css");
    c.IndexStream = () => GetType().Assembly
        .GetManifestResourceStream("YourNamespace.Swagger.index.html");
});

2. API Filtering

public class SwaggerFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // Remove internal endpoints
        foreach (var description in context.ApiDescriptions)
        {
            if (description.RelativePath.Contains("internal"))
                swaggerDoc.Paths.Remove($"/{description.RelativePath}");
        }

        // Custom tag ordering
        swaggerDoc.Tags = new List<OpenApiTag>
        {
            new OpenApiTag { Name = "Authentication", Description = "Auth endpoints" },
            new OpenApiTag { Name = "Data", Description = "Core data operations" }
        }.OrderBy(t => t.Name).ToList();
    }
}

3. Dynamic API Support

services.AddSwaggerGen(c =>
{
    c.DocInclusionPredicate((docName, apiDesc) => true);
});

ReDoc Integration

1. Installation

Install-Package Swashbuckle.AspNetCore.ReDoc

2. Configuration

app.UseReDoc(c =>
{
    c.DocumentTitle = "API Reference";
    c.SpecUrl = "/swagger/v1/swagger.json";
    c.RoutePrefix = "api-docs";
});

Key Features:

• Clean documentation-focused interface
• Responsive design
• Schema visualization
• Search functionality

---

Best Practices:

1. Secure Swagger endpoints in production environments
2. Implement rate limiting for documentation endpoints
3. Use operation filters for consistent security requirements
4. Combine with API versioning strategies
5. Regularly validate OpenAPI specification compliance

Production Considerations:

• Disable Swagger UI in production via environment checks
• Use Azure API Management for enterprise-grade documentation
• Implement caching for Swagger JSON endpoints
• Combine with API gateway solutions for microservices

Official Swashbuckle Documentation OpenAPI Specification Guide