Swagger / Swashbuckle у Minimal API: окремий класичний шлях

1. OpenAPI, Swagger UI, Swashbuckle: хто за що відповідає

Почнемо з найголовнішого розмежування.

Інженерна логіка така:

1. Minimal API endpoint-и містять metadata.
2. Swashbuckle читає цю metadata і генерує swagger.json.
3. Swagger UI в браузері читає цей JSON і малює інтерфейс.

flowchart LR
    A["Minimal API routes"] --> B["ApiExplorer metadata"]
    B --> C["Swashbuckle generator"]
    C --> D["/swagger/v1/swagger.json"]
    D --> E["Swagger UI /swagger"]

2. Коли обирати Swagger окремо від Scalar

Після статті про Scalar природно виникає питання: навіщо ще окремо вивчати Swagger?

Відповідь прагматична:

Висновок тут не ідеологічний, а прикладний:

• якщо система вже на Swashbuckle, потрібно вміти з ним працювати;
• якщо ви починаєте новий .NET 9+ проєкт, то Scalar зазвичай краще відповідає сучасному стеку цього курсу.

3. Відтворюваний проєкт на .NET 8

Щоб матеріал був не абстрактним, створимо окремий невеликий Minimal API-проєкт під Swagger.

Крок 1: Створення

mkdir MinimalApiSwaggerDemo
cd MinimalApiSwaggerDemo
dotnet new web --framework net8.0

mkdir MinimalApiSwaggerDemo
cd MinimalApiSwaggerDemo
dotnet new web --framework net8.0

Крок 2: Пакет Swashbuckle

dotnet add package Swashbuckle.AspNetCore

Крок 3: Що ми побудуємо

Так само, як у статті про Scalar, зробимо невеликий каталог товарів:

• GET /api/products
• GET /api/products/{id}
• POST /api/products
• PUT /api/products/{id}
• DELETE /api/products/{id}

Наприкінці перевіримо два URL:

• /swagger/v1/swagger.json
• /swagger

4. Структура проєкту

5. Що робить AddEndpointsApiExplorer()

Це один із тих рядків, які копіюють майже всі, але пояснюють далеко не всі.

builder.Services.AddEndpointsApiExplorer();

Для Minimal API цей сервісовий виклик критично важливий, бо саме він дає ApiExplorer знання про endpoint-и, створені через MapGet, MapPost, MapPut і так далі.

Якщо його прибрати:

• застосунок продовжить працювати;
• самі endpoint-и нікуди не зникнуть;
• але Swashbuckle перестане «бачити» Minimal API-маршрути так, як очікує генератор документації.

6. Що робить AddSwaggerGen()

Це вже серце інтеграції.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new()
    {
        Title = "Minimal API Swagger Demo",
        Version = "v1"
    });
});

Саме тут ми кажемо:

• що OpenAPI-документ взагалі треба згенерувати;
• як він називається;
• яку версію документа ми реєструємо;
• які додаткові налаштування застосувати.

Найважливіші можливості SwaggerGen

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new()
    {
        Title = "Catalog API",
        Version = "v1",
        Description = "Swagger UI demo for Minimal API"
    });

    options.SupportNonNullableReferenceTypes();

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

    if (File.Exists(xmlPath))
    {
        options.IncludeXmlComments(xmlPath);
    }
});

7. UseSwagger() і UseSwaggerUI(): чому це два різні виклики

У багатьох Program.cs вони стоять поряд, тому створюється ілюзія, що це «одна функція у двох рядках». Насправді це дві різні відповідальності.

app.UseSwagger();

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "Demo v1");
});

Простими словами:

• UseSwagger() = «віддай JSON»;
• UseSwaggerUI() = «віддай інтерфейс, який цей JSON показує».

8. Документування Minimal API endpoint-ів під Swagger

Найважливіше інженерне зауваження: Swagger UI не живе окремим життям. Якщо ви хочете, щоб UI був багатим і точним, metadata треба закладати в самі endpoint-и.

У Minimal API для цього достатньо Fluent API:

group.MapPost("/", CreateProduct)
    .WithName("CreateProduct")
    .WithSummary("Створити товар")
    .WithDescription("Створює товар і повертає 201 Created.")
    .Accepts<CreateProductRequest>("application/json")
    .Produces<ProductResponse>(StatusCodes.Status201Created)
    .ProducesValidationProblem(StatusCodes.Status422UnprocessableEntity)
    .ProducesProblem(StatusCodes.Status500InternalServerError)
    .WithOpenApi();

Що з цього реально потрапляє в Swagger UI

9. XML comments: коли вони ще корисні

Swagger historically дуже любить XML comments, і в екосистемі .NET 8 ви будете бачити їх часто.

Увімкнення в .csproj

<GenerateDocumentationFile>true</GenerateDocumentationFile>

Підключення в AddSwaggerGen

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

if (File.Exists(xmlPath))
{
    options.IncludeXmlComments(xmlPath);
}

Навіщо це потрібно

XML comments підтягують:

• summaries;
• descriptions;
• коментарі до моделей і властивостей.

Але тут є важлива практична межа.

Практичний висновок: у Minimal API Fluent API зазвичай читається краще, але XML comments усе ще залишаються корисним додатковим шаром, особливо для DTO та підтримки старих проєктів.

10. Кастомізація Swagger UI

Навіть базовий Swagger UI уже робочий, але в реальних системах його часто підлаштовують під інфраструктуру або UX-компроміси.

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "Demo v1");
});

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("./swagger/v1/swagger.json", "Demo v1");
    options.RoutePrefix = string.Empty;
});

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "Demo v1");
    options.DisplayRequestDuration();
});

На що звернути увагу

• SwaggerEndpoint(...) повинен вказувати на правильний JSON.
• RoutePrefix = string.Empty відкриває UI на корені сайту.
• відносний шлях ./swagger/v1/swagger.json корисний за reverse proxy або віртуальних директорій.

11. Безпека Swagger endpoint-ів

Помилка початківців: вважати, що якщо ваші API endpoint-и захищені, то documentation UI автоматично теж захищений. Це не так.

Окремо подумайте про:

• swagger.json;
• /swagger;
• доступність UI лише в development;
• потребу в авторизації.

Найпростіший варіант

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Це стандартний стартовий компроміс: документація доступна лише в development.

Захистити сам JSON-маршрут

Офіційні приклади Microsoft також показують варіант із:

app.MapSwagger().RequireAuthorization();

Такий підхід корисний, якщо UI або документ мають бути доступні тільки аутентифікованим користувачам.

12. Типові помилки зі Swagger у Minimal API

13. Практичні завдання

Рівень 1: Базовий

Рівень 2: Metadata

Рівень 3: Інфраструктура

14. Резюме