Swashbuckle для C# (.NET): полное руководство с примерами

Что такое Swashbuckle и зачем он нужен?

Swashbuckle — это мощная библиотека для платформы .NET, которая автоматически генерирует интерактивную документацию для ваших Web API на основе стандарта OpenAPI (ранее известного как Swagger). Она интегрируется непосредственно в ASP.NET Core приложения и позволяет разработчикам, тестировщикам и потребителям API легко понимать и взаимодействовать с вашими конечными точками.

Зачем это нужно?

• Автоматизация документации: Вам не нужно вручную писать и поддерживать документацию. Swashbuckle анализирует ваши контроллеры, модели и атрибуты, создавая актуальную документацию на лету.
• Интерактивный интерфейс (Swagger UI): Библиотека предоставляет веб-интерфейс, где можно просматривать все эндпоинты, их параметры, модели данных и даже выполнять тестовые запросы прямо из браузера.
• Стандартизация: OpenAPI — это отраслевой стандарт. Сгенерированная документация может быть использована для автоматической генерации клиентских SDK на разных языках (JavaScript, Python, Java и т.д.).
• Упрощение тестирования и отладки: Разработчики и QA-инженеры могут быстро тестировать API без использования сторонних инструментов вроде Postman (хотя Postman тоже может импортировать OpenAPI спецификацию).

Swashbuckle состоит из двух основных компонентов: Swashbuckle.AspNetCore.Swagger (генерация JSON-спецификации OpenAPI) и Swashbuckle.AspNetCore.SwaggerUI (отображение интерактивного интерфейса).

Установка

Swashbuckle устанавливается через менеджер пакетов NuGet. Вы можете использовать консоль диспетчера пакетов, .NET CLI или интерфейс Visual Studio.

Через .NET CLI (рекомендуется)

dotnet add package Swashbuckle.AspNetCore

Через Package Manager Console в Visual Studio

Install-Package Swashbuckle.AspNetCore

Эта команда установит основной пакет, который включает в себя все необходимые компоненты: Swagger, SwaggerUI и Swashbuckle.Core.

Быстрый старт с примером кода

Рассмотрим минимальную настройку Swashbuckle для ASP.NET Core Web API.

1. Создайте новый проект Web API

dotnet new webapi -n MySwaggerApi
cd MySwaggerApi

2. Добавьте Swashbuckle

dotnet add package Swashbuckle.AspNetCore

3. Настройте Program.cs

Откройте файл Program.cs и добавьте следующие строки:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Добавляем сервисы Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My Awesome API",
        Version = "v1",
        Description = "An example API to demonstrate Swashbuckle"
    });
});

var app = builder.Build();

// Включаем middleware для Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// Пример простого эндпоинта
var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

4. Запустите приложение

dotnet run

Перейдите по адресу http://localhost:5000/swagger (или https://localhost:5001/swagger). Вы увидите интерактивную документацию с вашим эндпоинтом /weatherforecast.

Основные методы и функции

Swashbuckle предоставляет множество методов для тонкой настройки документации. Ниже приведены 10 ключевых методов с примерами.

1. AddSwaggerGen()

Что делает: Регистрирует сервисы Swagger в DI-контейнере и позволяет настроить генератор спецификации OpenAPI.

Параметры: Принимает делегат Action<SwaggerGenOptions>, в котором можно настроить документы, фильтры, схемы и т.д.

Пример:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v2", new OpenApiInfo
    {
        Title = "My API v2",
        Version = "v2"
    });
});

2. SwaggerDoc()

Что делает: Определяет версию документа OpenAPI. Позволяет создавать несколько версий документации.

Параметры: name (строка, идентификатор версии, например "v1") и info (объект OpenApiInfo с метаданными).

Пример:

options.SwaggerDoc("v1", new OpenApiInfo
{
    Title = "My API",
    Version = "v1",
    Description = "First version of my API",
    Contact = new OpenApiContact
    {
        Name = "Developer",
        Email = "dev@example.com"
    }
});

3. UseSwagger()

Что делает: Включает middleware, который генерирует и отдает JSON-спецификацию OpenAPI по умолчанию по адресу /swagger/{documentName}/swagger.json.

Параметры: Необязательный делегат Action<SwaggerOptions> для настройки маршрута, сериализации и т.д.

Пример:

app.UseSwagger(c =>
{
    c.RouteTemplate = "api-docs/{documentName}/swagger.json";
    c.SerializeAsV2 = true; // Формат Swagger 2.0 вместо OpenAPI 3.0
});

4. UseSwaggerUI()

Что делает: Включает middleware для отображения интерактивного интерфейса Swagger UI.

Параметры: Делегат Action<SwaggerUIOptions> для настройки внешнего вида, URL спецификации, кастомизации.

Пример:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty; // Swagger UI будет доступен по корневому URL
    c.DocumentTitle = "My API Documentation";
});

5. IncludeXmlComments()

Что делает: Включает XML-комментарии из файла документации в спецификацию. Это позволяет использовать комментарии из кода (///) для описания эндпоинтов и моделей.

Параметры: Путь к XML-файлу (обычно генерируется при сборке).

Пример:

// В .csproj нужно включить генерацию XML-документации:
// <PropertyGroup>
//   <GenerateDocumentationFile>true</GenerateDocumentationFile>
// </PropertyGroup>

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

6. AddSecurityDefinition()

Что делает: Добавляет определение схемы безопасности (например, JWT Bearer, Basic Auth, API Key) в спецификацию.

Параметры: name (строка, идентификатор схемы) и securityScheme (объект OpenApiSecurityScheme).

Пример:

options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
    In = ParameterLocation.Header,
    Description = "Please enter JWT with Bearer into field",
    Name = "Authorization",
    Type = SecuritySchemeType.ApiKey,
    Scheme = "Bearer"
});

7. AddSecurityRequirement()

Что делает: Добавляет глобальное требование безопасности. Обычно используется вместе с AddSecurityDefinition.

Параметры: Объект OpenApiSecurityRequirement.

Пример:

options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference
            {
                Type = ReferenceType.SecurityScheme,
                Id = "Bearer"
            }
        },
        Array.Empty<string>()
    }
});

8. MapType()

Что делает: Позволяет сопоставить пользовательский тип данных с типом OpenAPI. Полезно для типов, которые не поддерживаются по умолчанию (например, FileResult).

Параметры: Type (исходный тип) и Func<Schema> (функция, возвращающая схему).

Пример:

options.MapType<IFormFile>(() => new OpenApiSchema
{
    Type = "string",
    Format = "binary"
});

9. OperationFilter<T>()

Что делает: Добавляет пользовательский фильтр операций. Фильтры позволяют модифицировать описание каждого эндпоинта (например, добавлять заголовки, параметры, описания).

Параметры: Generic-тип фильтра, реализующий интерфейс IOperationFilter.

Пример:

// Создаем фильтр
public class AddRequiredHeaderFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
            operation.Parameters = new List<OpenApiParameter>();

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "X-Custom-Header",
            In = ParameterLocation.Header,
            Required = true,
            Schema = new OpenApiSchema { Type = "string" }
        });
    }
}

// Регистрируем фильтр
options.OperationFilter<AddRequiredHeaderFilter>();

10. DocInclusionPredicate()

Что делает: Позволяет контролировать, какие эндпоинты включать в определенный документ. Полезно при создании нескольких версий API.

Параметры: Func<string, ApiDescription, bool> — предикат, который получает имя документа и описание эндпоинта, и возвращает true, если эндпоинт должен быть включен.

Пример:

options.DocInclusionPredicate((docName, apiDesc) =>
{
    // Включаем эндпоинты, которые имеют атрибут [ApiExplorerSettings(GroupName = "v1")]
    return apiDesc.GroupName == docName;
});

Реальный практический пример использования

Рассмотрим создание полноценного API для управления задачами (Task Manager) с JWT-аутентификацией и полной документацией.

Шаг 1: Создание модели и контроллера

// Models/TaskItem.cs
public class TaskItem
{
    public int Id { get; set;