Swagger/OpenAPI Configuration

Configure Swagger/OpenAPI documentation for your API.

For complete reference, see Library Guide.

Quick Start

appsettings.json

{
  "affolterNET": {
    "Web": {
      "Swagger": {
        "Enabled": true,
        "Title": "My API",
        "Version": "v1",
        "Description": "API documentation for My Application"
      }
    }
  }
}

Configuration Options

SwaggerOptions

Common Patterns

Development Only

{
  "affolterNET": {
    "Web": {
      "Swagger": {
        "Enabled": true
      }
    }
  }
}

In production, set Enabled to false or remove the configuration.

Custom Route

{
  "affolterNET": {
    "Web": {
      "Swagger": {
        "Enabled": true,
        "RoutePrefix": "api-docs"
      }
    }
  }
}

Access at: https://your-api.com/api-docs

With Authentication

When authentication is enabled, Swagger UI will include the authorization header configuration for testing authenticated endpoints.

Controller Documentation

Use XML comments for API documentation:

/// <summary>
/// Gets all users
/// </summary>
/// <returns>List of users</returns>
/// <response code="200">Returns the list of users</response>
/// <response code="401">Unauthorized</response>
[HttpGet]
[ProducesResponseType(typeof(List<User>), 200)]
[ProducesResponseType(401)]
public IActionResult GetUsers() { ... }

Enable XML documentation in your .csproj:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Troubleshooting

Swagger UI not loading

• Verify Enabled is true in configuration
• Check the RoutePrefix matches your expected URL
• Ensure no middleware is blocking the Swagger routes

Missing endpoints

• Confirm controllers are properly registered
• Check that routes are correctly attributed
• Verify authorization doesn't block discovery