Swagger/OpenAPI генерация C# (.NET)

Swagger/OpenAPI генерация для C# (.NET)

Swagger (теперь официально известный как OpenAPI) — это мощный инструмент для проектирования, создания, документирования и использования RESTful API. В экосистеме .NET генерация спецификаций OpenAPI и интерактивной документации стала неотъемлемой частью разработки современных веб-сервисов. В этой статье мы подробно рассмотрим, как настроить автоматическую генерацию Swagger/OpenAPI в приложениях C# (.NET), используя библиотеку Swashbuckle.AspNetCore.

Swagger позволяет не только автоматически создавать читаемую документацию, но и предоставляет интерактивный интерфейс (Swagger UI) для тестирования эндпоинтов прямо из браузера. Это значительно ускоряет разработку и интеграцию между командами.

Установка и настройка Swashbuckle в .NET

Для начала работы нам потребуется установить пакет Swashbuckle.AspNetCore. Это основной пакет, который включает в себя генератор Swagger, Swagger UI и интеграцию с ASP.NET Core.

Установка через NuGet Package Manager Console:

Install-Package Swashbuckle.AspNetCore

Или через .NET CLI:

dotnet add package Swashbuckle.AspNetCore

После установки пакета необходимо настроить сервисы в файле Program.cs (или Startup.cs для более старых версий). Рассмотрим минимальную конфигурацию для .NET 8 и выше:

var builder = WebApplication.CreateBuilder(args);

// Добавляем сервисы Swagger
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "Пример API с документацией Swagger"
    });
});

builder.Services.AddControllers();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

app.UseHttpsRedirection();
app.MapControllers();

app.Run();

Основные возможности Swashbuckle

Автоматическая генерация спецификации OpenAPI — библиотека анализирует ваши контроллеры, модели данных и атрибуты, создавая JSON/YAML файл спецификации.
Интерактивный Swagger UI — веб-интерфейс, в котором можно просматривать эндпоинты, отправлять запросы и видеть ответы.
Поддержка XML-комментариев — если вы добавите XML-документацию к вашим контроллерам и моделям, Swagger отобразит их в интерфейсе.
Группировка по версиям — можно создавать несколько версий документации для разных версий API.
Кастомизация — возможность настраивать внешний вид, добавлять заголовки, схемы аутентификации (JWT, Basic Auth) и многое другое.

Добавление XML-комментариев для документации

Чтобы ваша документация была информативной, используйте XML-комментарии. Сначала включите генерацию XML-файла в проекте. Откройте .csproj файл и добавьте:

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

Затем укажите путь к XML-файлу в AddSwaggerGen:

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    
    // Указываем путь к XML-файлу документации
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

Теперь комментарии из вашего кода будут отображаться в Swagger UI. Пример контроллера с комментариями:

/// <summary>
/// Контроллер для управления пользователями.
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    /// <summary>
    /// Получить пользователя по ID.
    /// </summary>
    /// <param name="id">Уникальный идентификатор пользователя.</param>
    /// <returns>Объект пользователя.</returns>
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        // Логика получения пользователя
        return Ok(new { Id = id, Name = "John Doe" });
    }
}