OpenAPI и Swagger
Тема дорожной карты · Backend разработчик
OpenAPI / Swagger — независимый от языка стандарт спецификации для описания REST API в машиночитаемом формате YAML или JSON, обеспечивающий автоматическую генерацию документации, клиентских SDK, серверных заглушек и контрактных тестов из единственного источника истины. Спецификация OpenAPI (ранее Swagger) определяет эндпоинты, HTTP-методы, схемы запросов/ответов, схемы аутентификации (включая OAuth 2.0 и JWT bearer-токены) и ожидаемые коды состояния HTTP, обеспечивая потребителей API точным контрактом для написания кода. Swagger UI отображает спецификации OpenAPI в виде интерактивной документации, где разработчики могут выполнять live-запросы непосредственно в браузере, значительно снижая порог вхождения для новых потребителей REST API. Фреймворки Spring Boot (через springdoc-openapi), FastAPI (нативно), ASP.NET Core (через Swashbuckle) и NestJS автоматически генерируют документацию OpenAPI / Swagger из аннотаций кода, поддерживая документацию в синхронизации с реализацией через CI/CD-пайплайны. Спецификации OpenAPI могут храниться в системе контроля версий и проверяться инструментами вроде spectral, обеспечивая рабочие процессы API-first разработки, где спецификация рецензируется и утверждается до начала бэкенд-реализации.
Как это работает
OpenAPI и Swagger имеет три доминирующих стиля: REST (resource-oriented, использует HTTP-семантику, легко кешируется), GraphQL (клиент выбирает форму, один endpoint, хорошо для разных клиентов), gRPC/RPC (вызов процедур, строгая схема, низкий overhead). Хороший API предсказуем: консистентные имена, версионирован (/v1/users), пагинация для коллекций (курсор лучше offset), фильтруем, идемпотентен где безопасно, задокументирован (OpenAPI для REST, .proto для gRPC, schema для GraphQL).
Когда применять
REST — для публичных API, которые потребляет много третьих сторон: lowest common denominator. GraphQL — когда один backend обслуживает много форм клиента (web + iOS + Android с разными нуждами) и хотите избежать bespoke endpoint на клиента. gRPC — для internal service-to-service, где важны latency + типизированные контракты. Микс ок: публичный REST + internal gRPC — частый кейс.
Типичные ошибки
Ловушки OpenAPI и Swagger: нет версионирования ("добавим версию потом" — к тому моменту breaking change для всех); глубоко вложенные ресурсы (/users/123/orders/456/items/789 — плоский лучше); chatty API (клиент делает 10 вызовов на одну страницу — батчите или expand related); утечка внутренних ID (auto-increment integer выдаёт объём — UUID лучше); непоследовательный формат ошибок. Пишите доки API так, будто их прочитает незнакомец.