Документация API: OpenAPI/Swagger

Документация API: OpenAPI/Swagger, чтобы API был понятен без чтения кода.

Суть: OpenAPI (бывший Swagger) — стандарт описания HTTP-API в машиночитаемом виде. По нему генерируется интерактивная документация и клиентский код. В ASP.NET Core документация генерируется автоматически из ваших контроллеров и DTO.

Хороший API бесполезен, если непонятно, как им пользоваться. Документация отвечает на вопросы: какие есть эндпоинты, что они принимают, что возвращают. Писать её руками — мука, поэтому её генерируют из кода.

Подключение

В .NET 8 встроена генерация OpenAPI-документа, а для UI обычно добавляют Swagger UI или Scalar:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
// ...
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Запустите приложение и откройте /swagger — увидите список эндпоинтов, их параметры, схемы DTO и кнопку «Try it out», чтобы вызвать API прямо из браузера.

Как работает под капотом

Генератор сканирует ваши контроллеры, читает атрибуты маршрутов, типы параметров и возвращаемых значений, аннотации валидации — и строит JSON-документ по спецификации OpenAPI. Swagger UI — это страница, которая читает этот JSON и рисует интерактивный интерфейс. Чем точнее типизированы методы (ActionResult<UserDto>, атрибуты [ProducesResponseType]), тем полнее документация.

Частые ошибки

Оставить Swagger UI включённым в проде. Часто его прячут за dev-окружение или авторизацию — публичный UI раскрывает структуру API.
Возвращать IActionResult без указания типов. Тогда в документации не видно, что именно вернётся — добавьте [ProducesResponseType].
Не описывать коды ошибок. Документируйте не только 200, но и 400/404/401.

Best practices

Используйте XML-комментарии к методам — они попадают в документацию как описания.
Помечайте возможные ответы через [ProducesResponseType] с нужными статус-кодами.
По OpenAPI-документу можно автогенерировать клиентов (TypeScript, C#) — это убирает ручную работу на фронте.

Что описывает OpenAPI и зачем это машиночитаемо

OpenAPI-документ — это структурированное (JSON/YAML) описание всего API: пути, методы, параметры, схемы запросов и ответов, коды, требования авторизации. Ключевое слово — машиночитаемое. Из этого документа автоматически генерируются интерактивный UI (Swagger UI, Scalar), клиентские SDK на разных языках, моки для тестов, проверки контракта в CI. Один источник правды описывает API сразу для людей и для инструментов.

Чем точнее типизирован код, тем богаче документ. Возврат ActionResult<UserDto>, атрибуты [ProducesResponseType(StatusCodes.Status200OK)] и [ProducesResponseType(StatusCodes.Status404NotFound)], XML-комментарии к методам — всё это подхватывается генератором. В результате потребитель видит не только «какие есть ручки», но и какие коды возможны и какова форма каждого ответа.

Документация как часть контракта и безопасность

Хорошая документация снижает трение: фронтенд-разработчик или партнёр интегрируется, не дёргая вас вопросами и не читая исходники. Поэтому её держат в актуальном состоянии вместе с кодом — благо она и генерируется из кода, а значит не «отстаёт». В зрелых командах OpenAPI-документ ещё и проверяют в CI на обратную совместимость: если изменение ломает контракт, сборка падает, и поломка не доезжает до клиентов.

При этом интерактивный UI в проде — палка о двух концах. Он удобен, но раскрывает всю структуру API потенциальному злоумышленнику. Распространённая практика — оставлять Swagger UI только в Development/Staging, а в Production либо отключать, либо прятать за авторизацией. Сам OpenAPI-документ при необходимости отдают доверенным потребителям отдельно. Безопасность здесь важнее удобства публичного доступа к схеме.

Итог: OpenAPI/Swagger превращает ваш код в живую документацию и снижает трение для потребителей API. Дальше — раздел про работу с базой данных через EF Core.