Что такое Swagger (OpenAPI) в контексте ASP.NET Core?

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

Что это даёт?

1. Автодокументирование: Документация всегда актуальна, так как генерируется из кода (контроллеров, моделей, атрибутов).
2. Интерактивный UI (Swagger UI): Веб-интерфейс для просмотра всех endpoints, их параметров, моделей данных и, что самое важное, для непосредственного выполнения тестовых запросов к вашему API.
3. Стандартизация: Генерируется JSON-файл в формате OpenAPI, который можно использовать в других инструментах (генераторы клиентского кода, импорт в Postman, API-гейтвеи).

Базовое подключение в ASP.NET Core 6+:

// Program.cs
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// 1. Добавляем сервисы генерации Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My Product API",
        Version = "v1",
        Description = "API для управления каталогом товаров",
        Contact = new OpenApiContact { Name = "Dev Team", Email = "dev@example.com" }
    });
    // Можно добавить авторизацию для UI
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "JWT Authorization header. Example: 'Bearer {token}'",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });
});

var app = builder.Build();

// 2. Подключаем middleware Swagger в конвейер (только для Development)
if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // Генерирует JSON-спецификацию по маршруту /swagger/v1/swagger.json
    app.UseSwaggerUI(c => // Обслуживает веб-интерфейс по маршруту /swagger
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        // c.RoutePrefix = string.Empty; // Чтобы UI открывался на корневом маршруте
    });
}

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

Улучшение документации с помощью атрибутов:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class ProductsController : ControllerBase
{
    /// <summary>
    /// Получает товар по его уникальному идентификатору.
    /// </summary>
    /// <param name="id">Идентификатор товара.</param>
    /// <returns>Объект товара.</returns>
    /// <response code="200">Товар успешно найден.</response>
    /// <response code="404">Товар с указанным ID не существует.</response>
    [HttpGet("{id}")]
    [ProducesResponseType(typeof(Product), StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public IActionResult GetById(int id)
    {
        // ... логика
        return Ok(new Product { Id = id, Name = "Sample" });
    }

    [HttpPost]
    [Consumes("application/json")]
    [ProducesResponseType(typeof(Product), StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public IActionResult Create([FromBody] CreateProductDto dto)
    {
        // ... логика создания
        return CreatedAtAction(nameof(GetById), new { id = 1 }, dto);
    }
}

После запуска приложения откройте https://your-host/swagger — вы увидите полный список API с возможностью «попробовать» любой endpoint.

Итог:

Swashbuckle/Swagger — это must-have инструмент для современных .NET Web API проектов. Он ускоряет разработку (особенно в командах с фронтенд-разработчиками), упрощает тестирование и обеспечивает наличие живой, актуальной документации.