Что хотят услышать интервьюеры:

Важно показать, что Swagger использовался не только как “красивая документация”, но и как рабочий инструмент для проверки API. Хорошо, если есть опыт интеграции Swagger в ASP.NET Core, описания контрактов и тестирования эндпоинтов через UI. Также плюс, если понятно, как Swagger помогает синхронизировать фронтенд и бэкенд.

Определение:

Swagger — это набор инструментов для описания, документирования и интерактивного тестирования REST API. В экосистеме .NET чаще всего используют Swagger/OpenAPI через Swagger UI, чтобы автоматически получать документацию по контроллерам, моделям и маршрутам, а также отправлять запросы прямо из браузера.

Пример использования:

В ASP.NET Core Swagger подключают в проект, чтобы после запуска приложения открыть страницу с документацией API, посмотреть список контроллеров и протестировать запросы без Postman.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

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

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

Например, для метода GET /api/users/{id} Swagger покажет параметры, схему ответа и позволит отправить тестовый запрос прямо из интерфейса.

Пояснение кода:

AddEndpointsApiExplorer() — включает сбор информации о маршрутах и эндпоинтах.
AddSwaggerGen() — подключает генерацию Swagger/OpenAPI-спецификации.
UseSwagger() — публикует JSON-описание API.
UseSwaggerUI() — включает веб-интерфейс для просмотра и тестирования API.
if (app.Environment.IsDevelopment()) — обычно Swagger включают только в development, чтобы не светить лишнюю информацию в production.

Ключевые моменты:

Swagger полезен и для документации, и для быстрой проверки API без дополнительных инструментов.
В ASP.NET Core он обычно подключается через AddSwaggerGen, UseSwagger, UseSwaggerUI.
Он автоматически строит описание по контроллерам, атрибутам и моделям, если проект настроен корректно.
Через Swagger UI удобно проверять входные параметры, коды ответов и контракт JSON.
Для команды это хороший способ держать API-документацию актуальной вместе с кодом.

Имели ли вы опыт использования инструмента Swagger для документирования и тестирования API?