Indiko.Blocks.API.Swagger 2.1.2

Indiko.Blocks.API.Swagger

Swagger/OpenAPI documentation block for generating interactive API documentation with authentication support and API versioning.

Overview

This package provides automatic Swagger/OpenAPI documentation generation for ASP.NET Core Web APIs, with built-in support for JWT Bearer authentication, API versioning, XML documentation, and custom filters.

Features

• Swagger UI: Interactive API documentation and testing interface
• OpenAPI 3.0: Standard OpenAPI specification generation
• API Versioning: Automatic versioning support with URL segments
• JWT Authentication: Built-in Bearer token authentication UI
• XML Documentation: Automatic XML comment inclusion
• Custom Filters: Operation filters for enhanced documentation
• Deep Linking: Direct links to specific API operations
• Deprecated APIs: Visual indicators for deprecated endpoints
• Response Examples: Support for request/response examples
• Auto-Discovery: Automatic endpoint discovery

Installation

dotnet add package Indiko.Blocks.API.Swagger

Quick Start

Enable Swagger Block

using Indiko.Hosting.Web;

public class Startup : WebStartup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    protected override bool AddControllersWithViews => false;
    protected override bool EnableForwardedHeaderOptions => false;
    protected override bool ForceHttps => true;
    
    // Swagger is automatically enabled via block system
}

Configuration (appsettings.json)

{
  "SwaggerOptions": {
    "Enabled": true,
    "Title": "My API",
    "Description": "RESTful API for My Application",
    "ApiPrefix": "api",
    "TermsOfService": "https://example.com/terms",
    "Contact": {
      "Name": "API Support",
      "Email": "support@example.com",
      "Url": "https://example.com/support"
    },
    "License": {
      "Name": "MIT",
      "Url": "https://opensource.org/licenses/MIT"
    }
  }
}

Access Swagger UI

Once configured, Swagger UI is available at:

https://localhost:5001/

Or specifically:

https://localhost:5001/swagger

API Versioning

Define Versioned Controllers

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class UsersController : ControllerBase
{
    /// <summary>
    /// Gets all users
    /// </summary>
    /// <returns>List of users</returns>
    /// <response code="200">Returns the list of users</response>
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public async Task<IActionResult> GetUsers()
    {
        // Implementation
        return Ok(users);
    }
    
    /// <summary>
    /// Gets a specific user by ID
    /// </summary>
    /// <param name="id">User ID</param>
    /// <returns>User details</returns>
    /// <response code="200">Returns the user</response>
    /// <response code="404">User not found</response>
    [HttpGet("{id}")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public async Task<IActionResult> GetUser(Guid id)
    {
        // Implementation
        return Ok(user);
    }
}

Multiple API Versions

// Version 1.0
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class UsersV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetUsers()
    {
        // V1 implementation
        return Ok(usersV1);
    }
}

// Version 2.0
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class UsersV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetUsers()
    {
        // V2 implementation with more features
        return Ok(usersV2);
    }
}

// Deprecated version
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0", Deprecated = true)]
public class OrdersV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        // Old implementation
        return Ok(orders);
    }
}

XML Documentation

Enable XML Documentation in Project

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn> 
  </PropertyGroup>
</Project>

Document Your APIs

/// <summary>
/// User management controller
/// </summary>
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersController : ControllerBase
{
    /// <summary>
    /// Creates a new user
    /// </summary>
    /// <param name="command">User creation data</param>
    /// <returns>Created user ID</returns>
    /// <remarks>
    /// Sample request:
    /// 
    ///     POST /api/v1/users
    ///     {
    ///        "firstName": "John",
    ///        "lastName": "Doe",
    ///        "email": "john.doe@example.com"
    ///     }
    /// 
    /// </remarks>
    /// <response code="201">User created successfully</response>
    /// <response code="400">Invalid request data</response>
    /// <response code="409">Email already exists</response>
    [HttpPost]
    [ProducesResponseType(typeof(Guid), StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [ProducesResponseType(StatusCodes.Status409Conflict)]
    public async Task<IActionResult> CreateUser([FromBody] CreateUserCommand command)
    {
        var userId = await _mediator.Send<CreateUserCommand, Guid>(command);
        return CreatedAtAction(nameof(GetUser), new { id = userId }, userId);
    }
}

Authentication Documentation

JWT Bearer Authentication

The Swagger UI includes built-in JWT Bearer token authentication:

1. Click the "Authorize" button at the top right
2. Enter your token in the format: Bearer {your-token}
3. Click "Authorize"
4. All subsequent requests include the token

Require Authentication

using Microsoft.AspNetCore.Authorization;

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[Authorize] // Requires authentication for all actions
public class SecureController : ControllerBase
{
    [HttpGet]
    public IActionResult GetSecureData()
    {
        return Ok(secureData);
    }
    
    [HttpPost]
    [AllowAnonymous] // Allow anonymous access to specific action
    public IActionResult PublicEndpoint()
    {
        return Ok("Public data");
    }
}

Custom Attributes

Implementation Notes

using Indiko.Blocks.API.Swagger.Attributes;

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [ImplementationNotes("This endpoint returns a cached list of products. Cache expires after 5 minutes.")]
    public IActionResult GetProducts()
    {
        return Ok(products);
    }
}

Request/Response Examples

Using Swashbuckle Annotations

using Swashbuckle.AspNetCore.Annotations;

public class CreateUserCommand
{
    /// <example>John</example>
    public string FirstName { get; set; }
    
    /// <example>Doe</example>
    public string LastName { get; set; }
    
    /// <example>john.doe@example.com</example>
    public string Email { get; set; }
}

[HttpPost]
[SwaggerOperation(
    Summary = "Creates a new user",
    Description = "Creates a new user account with the provided information",
    OperationId = "CreateUser",
    Tags = new[] { "Users" }
)]
[SwaggerResponse(201, "User created successfully", typeof(Guid))]
[SwaggerResponse(400, "Invalid request data")]
[SwaggerResponse(409, "Email already exists")]
public async Task<IActionResult> CreateUser([FromBody] CreateUserCommand command)
{
    var userId = await _mediator.Send<CreateUserCommand, Guid>(command);
    return CreatedAtAction(nameof(GetUser), new { id = userId }, userId);
}

Custom Operation Filters

The block includes several built-in filters:

AddBearerAuthHeaderOperationFilter

Adds Bearer token authentication to operations with [Authorize] attribute.

AuthenticationResponseCodesOperationFilter

Automatically adds 401 (Unauthorized) and 403 (Forbidden) response codes to secured endpoints.

ImplementationNotesAttributeFilter

Processes [ImplementationNotes] attribute and adds notes to Swagger documentation.

LowercaseDocumentsFilter

Converts all URLs to lowercase in the Swagger documentation.

Advanced Configuration

Custom Swagger Options

public class CustomSwaggerBlock : SwaggerBlock
{
    public CustomSwaggerBlock(IConfiguration configuration, ILogger logger) 
        : base(configuration, logger)
    {
    }

    public override void ConfigureServices(IServiceCollection services)
    {
        base.ConfigureServices(services);
        
        // Add custom filters
        services.Configure<SwaggerGenOptions>(options =>
        {
            options.OperationFilter<MyCustomOperationFilter>();
            options.DocumentFilter<MyCustomDocumentFilter>();
        });
    }
}

Group by Tags

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[Tags("User Management")]
public class UsersController : ControllerBase
{
    // All endpoints grouped under "User Management"
}

Security Schemes

OAuth2 Configuration

services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("OAuth2", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.OAuth2,
        Flows = new OpenApiOAuthFlows
        {
            AuthorizationCode = new OpenApiOAuthFlow
            {
                AuthorizationUrl = new Uri("https://identity.example.com/connect/authorize"),
                TokenUrl = new Uri("https://identity.example.com/connect/token"),
                Scopes = new Dictionary<string, string>
                {
                    { "api", "API Access" },
                    { "profile", "Profile Access" }
                }
            }
        }
    });
});

File Upload Documentation

/// <summary>
/// Uploads a file
/// </summary>
/// <param name="file">File to upload</param>
[HttpPost("upload")]
[Consumes("multipart/form-data")]
[ProducesResponseType(StatusCodes.Status200OK)]
public async Task<IActionResult> UploadFile(IFormFile file)
{
    // Implementation
    return Ok(new { FileName = file.FileName, Size = file.Length });
}

Enum Documentation

/// <summary>
/// User status
/// </summary>
public enum UserStatus
{
    /// <summary>User is active</summary>
    Active = 0,
    
    /// <summary>User is inactive</summary>
    Inactive = 1,
    
    /// <summary>User is suspended</summary>
    Suspended = 2
}

Best Practices

1. Always Add XML Comments: Document all public APIs with XML comments
2. Use ProducesResponseType: Specify all possible response types
3. Version Your APIs: Use semantic versioning (v1.0, v2.0)
4. Group Related Endpoints: Use Tags to organize endpoints
5. Example Values: Provide example values for properties
6. Deprecation: Mark deprecated endpoints clearly
7. Security: Document authentication requirements
8. Error Responses: Document all possible error scenarios

Swagger UI Features

• Try it out: Test endpoints directly from the browser
• Model Schemas: View request/response models
• Authorization: Test authenticated endpoints
• Download Spec: Download OpenAPI specification (JSON/YAML)
• Deep Linking: Share links to specific endpoints
• Code Generation: Generate client code

Production Considerations

Disable in Production

public override void Configure(IApplicationBuilder app, IServiceProvider serviceProvider, IHostEnvironment environment)
{
    if (environment.IsDevelopment())
    {
        base.Configure(app, serviceProvider, environment);
    }
}

Or with Configuration

{
  "SwaggerOptions": {
    "Enabled": false  // Disable in production
  }
}

URL Routing

Swagger UI is available at multiple URLs:

• / - Root (default)
• /swagger - Explicit Swagger path
• /swagger/v1/swagger.json - OpenAPI spec for v1
• /swagger/v2/swagger.json - OpenAPI spec for v2

Target Framework

• .NET 10

Dependencies

• Swashbuckle.AspNetCore (6.5+)
• Swashbuckle.AspNetCore.Filters
• Swashbuckle.AspNetCore.Annotations
• Asp.Versioning.Mvc.ApiExplorer
• Indiko.Blocks.Common.Abstractions

License

See LICENSE file in the repository root.

Related Packages

• Indiko.Blocks.API.Compression - Response compression
• Indiko.Blocks.API.FeatureManagement - Feature flags
• Indiko.Blocks.API.Idempotency - Idempotent requests
• Indiko.Blocks.Security.Authentication.ASPNetCore - Authentication

Resources

• Swashbuckle Documentation
• OpenAPI Specification