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

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

Документирование REST API — неотъемлемая часть современной разработки на C# (.NET). Спецификация OpenAPI (ранее известная как Swagger) позволяет описать эндпоинты, модели данных, параметры и ответы в едином, машиночитаемом формате (JSON/YAML). В экосистеме .NET Core / .NET 5+ существуют два основных инструмента для автоматической генерации OpenAPI-спецификации: Swashbuckle.AspNetCore и NSwag. Оба инструмента интегрируются в ASP.NET Core, анализируют ваш код и создают интерактивную документацию (Swagger UI).

Swashbuckle.AspNetCore: классический выбор

Swashbuckle — самый популярный пакет для генерации Swagger/OpenAPI в .NET. Он автоматически строит спецификацию на основе контроллеров, атрибутов маршрутизации и аннотаций к моделям. Поддерживает OpenAPI 3.0 и Swagger 2.0.

Установка и базовая настройка

dotnet add package Swashbuckle.AspNetCore

В файле Program.cs (или Startup.cs для старых версий) добавьте сервисы и middleware:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Мое API",
        Version = "v1",
        Description = "Пример API для образовательного сайта"
    });
});

var app = builder.Build();

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

app.MapControllers();
app.Run();

После запуска перейдите по адресу /swagger — откроется интерактивный UI, где можно тестировать эндпоинты прямо из браузера.

Добавление комментариев XML

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

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

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

builder.Services.AddSwaggerGen(c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

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

Пример контроллера с аннотациями

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    /// <summary>
    /// Получить список всех продуктов
    /// </summary>
    [HttpGet]
    public ActionResult<IEnumerable<Product>> GetAll()
    {
        return Ok(new List<Product>());
    }

    /// <summary>
    /// Получить продукт по ID
    /// </summary>
    /// <param name="id">Идентификатор продукта</param>
    [HttpGet("{id}")]
    public ActionResult<Product> GetById(int id)
    {
        return Ok(new Product { Id = id, Name = "Пример" });
    }
}

NSwag: универсальный инструмент с генерацией клиентов

NSwag — более мощная альтернатива. Помимо генерации документации, он умеет создавать C#-клиенты для API, TypeScript-клиенты, а также генерировать код на основе внешних OpenAPI-спецификаций.

Установка и настройка

dotnet add package NSwag.AspNetCore

Настройка в Program.cs:

builder.Services.AddOpenApiDocument(config =>
{
    config.Title = "Мое API (NSwag)";
    config.Version = "v1";
    config.Description = "API, сгенерированное с помощью NSwag";
});

// ...

if (app.Environment.IsDevelopment())
{
    app.UseOpenApi();
    app.UseSwaggerUi3(); // или app.UseSwaggerUi();
}

NSwag автоматически поддерживает OpenAPI 3.0. UI доступен по адресу /swagger.

Генерация клиента на C#

NSwag позволяет сгенерировать C#-клиент для вашего API прямо из командной строки или через MSBuild:

nswag aspnetcore /runtime:Net60 /assembly:MyApi.dll /output:client.cs

Или используйте файл конфигурации nswag.json:

                
    

  
Также в библиотеке
  

                
                  
                 JSON обработка в TypeScript: типизация, парсинг и валидация данных
      
                
                  
                 HTTP-клиент для TypeScript: топ библиотек для веб-разработки
      
                
                  
                 Invoke – управление задачами
      
                
                  
                 Отправка email на Go (Golang): библиотеки и примеры кода
      
                
                  
                 Работа с S3 и облачными хранилищами в C# (.NET): библиотека AWS SDK