Мой дэйли дайджест

одно техническое понятие в день

OpenAPI (Swagger)

30 августа 2026 · ~14 мин чтения

спецификация api стандарт инструмент документация

OpenAPI (Swagger)

OpenAPI — это машиночитаемое описание HTTP-API: какие адреса есть, что они принимают, что отвечают, как проверять аутентификацию. Раньше называлось Swagger. Файл на YAML или JSON, единый для всех клиентов и серверов.

История

История OpenAPI — это ровно та история, где инженерное решение переросло автора и стало общей нормой.

Начало — 2010 год, США. Разработчик по имени Тони Там (Tony Tam) делал в компании Wordnik (проект-словарь) внутренний инструмент, чтобы описывать их REST-API одним файлом. Проект назывался Swagger и был из двух частей: спецификация (формат JSON, как описывать API) и Swagger UI (веб-страничка, которая читает этот файл и рисует красивую документацию с кнопкой «попробовать»). Он выложил всё в открытый доступ на GitHub.

Идея выстрелила потому, что попала в больной нерв эпохи. Начало 2010-х — расцвет REST-API: все делали микросервисы, все делали мобильные приложения к своим бэкендам, все делали публичные API для сторонних разработчиков. И у всех была одна и та же проблема: как поддерживать документацию в актуальном состоянии, чтобы она не отставала от реального кода. Swagger отвечал: не поддерживайте руками, храните описание одним файлом и генерируйте документацию, клиентов и заглушки из него.

Дальше — 2015 год. Swagger покупает компания SmartBear (они делают тестировочные инструменты). И через несколько месяцев SmartBear передаёт спецификацию под крыло Linux Foundation, создаётся OpenAPI Initiative — консорциум, куда сразу входят Google, Microsoft, IBM, PayPal, Atlassian и другие. Именно тогда спецификация переименовывается: сам стандарт теперь OpenAPI Specification (OAS), а имя Swagger остаётся у инструментов (Swagger UI, Swagger Editor, Swagger Codegen).

Вехи развития:

Кто владеет стандартом сегодня — OpenAPI Initiative (openapis.org), это некоммерческий проект Linux Foundation. Спецификация свободная, лицензия Apache 2.0. Инструменты — частично тоже открытые (Swagger UI, Redoc, openapi-generator), частично коммерческие (SwaggerHub от SmartBear).

Что это такое

Представь, что у тебя есть HTTP-сервис. Он умеет отвечать на десяток адресов: GET /users, POST /users, GET /users/{id}, и так далее. Чтобы этим сервисом кто-то мог пользоваться, нужно рассказать миру:

OpenAPI — это способ рассказать всё это одним файлом, в машиночитаемом виде. Открываешь openapi.yaml, а там:

openapi: 3.1.0
info:
  title: Users API
  version: 1.2.0
paths:
  /users/{id}:
    get:
      summary: Получить пользователя по id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Не найден
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        name:
          type: string

Это описание — контракт. Оно говорит: сервис обязуется принимать такие запросы и отвечать такими телами. И одновременно оно машиночитаемое — то есть по нему автоматически строятся: документация (Swagger UI, Redoc), клиентские библиотеки на любом языке (openapi-generator), моки для тестов, валидация входящих запросов на сервере, коллекции в Postman.

Чем отличается от похожих вещей.

Аналогии из жизни

Меню в ресторане. OpenAPI — это меню сервиса. В меню написано: «Комбо №3: две котлеты, картошка, соус на выбор — томатный или горчичный, 480 рублей». Гость (клиент API) заранее знает, что можно заказать и что придёт в тарелке. Официант (сервер) не имеет права принести пельмени вместо котлет — контракт.
Где ломается. В меню нельзя описать логику: «если сегодня пятница, то мороженое бесплатно». В OpenAPI тоже нельзя описать бизнес-правила — только форму запроса и ответа. То, что должно случиться внутри, остаётся на честном слове разработчика.

Спецификация розетки евростандарта. Есть стандарт CEE 7/4: два круглых штыря, заземление сверху, 230 вольт, 50 герц. Любой производитель вилок и розеток по всему миру знает точно, что и где должно быть. Ты покупаешь фен в одном магазине, розетку в другом — они совпадают, потому что оба соответствуют одному стандарту. OpenAPI — это такая же розетка, только для программ.
Где ломается. Розетка ничего не говорит про то, что через неё потечёт. Она гарантирует форму — но фен, стиральная машина и лампочка ведут себя очень по-разному. OpenAPI гарантирует, что тело запроса пройдёт валидацию, но не гарантирует, что бэкенд сделает то, что ты ожидаешь семантически.

Договор поставки в бизнесе. В договоре прописано: поставщик поставляет 100 коробок такого-то артикула, к такому-то числу, по такой-то цене, оплата в течение 15 дней после отгрузки, любые изменения — приложением. Обе стороны знают, чего ждать; в случае спора — разбираются по договору. OpenAPI — тот же договор, только между двумя сервисами: клиент шлёт вот такое, сервер отвечает вот таким, срок ответа не оговорён, версия 1.2.0.
Где ломается. Договор поставки заверен подписями и юридически обязывает. OpenAPI сам по себе никого ни к чему не обязывает: если разработчик пишет одно в файле, а делает в коде другое — до момента, пока никто автоматически не сверил, обе стороны об этом даже не узнают.

Как это работает

По шагам, как всё это устроено на практике.

Шаг 1. Пишется файл спецификации. Обычно openapi.yaml или openapi.json. Внутри — три главных блока:

Шаг 2. Файл валидируется. Есть валидаторы (Spectral, openapi-cli), которые проверяют, что вы написали корректный OpenAPI, что нет пропущенных обязательных полей, что все $ref — ссылки на существующие места, что схемы соответствуют JSON Schema. Обычно это встраивается в CI (continuous integration — автоматическая проверка при каждом коммите): не проходит проверку — не мержим.

Шаг 3. Из файла генерируется всё, что можно генерировать.

Шаг 4. Спецификация живёт вместе с кодом. Есть две философии, и они спорят.

На практике часто гибрид: пишут код с аннотациями (code-first), но спецификация после генерации становится тем самым файлом, по которому потом все синхронизируются.

Шаг 5. Клиенты используют. Мобильный разработчик, фронтендер, сторонний интегратор — они не читают ваш код на бэкенде. Они открывают Swagger UI, читают, что можно, генерируют клиента под свой язык и начинают работать.

Схематично весь цикл:

разработчик пишет код + аннотации
       ↓
фреймворк генерирует openapi.json
       ↓
      ├── Swagger UI → люди читают доку
      ├── openapi-generator → клиентские SDK
      ├── Prism → мок-сервер для тестов
      └── валидатор в CI → проверка при каждом коммите

Где встречается в обычной жизни

Где встречается в IT и бизнесе

Кто пользуется

Проще перечислить, кто не пользуется. Но конкретно:

Масштаб: по данным сайта openapis.org и опросам SmartBear, более 75% публичных REST API в мире описаны в OpenAPI, и это доля растёт каждый год.

Альтернативы и конкуренты

RAML (RESTful API Modeling Language). Появился в 2013 у MuleSoft, тоже YAML, тоже про REST. Плюсы: чуть более удобный синтаксис в спорах фанатов, хорошо работает с тем, что называет modularity. Минусы: комьюнити почти умерло, MuleSoft купили Salesforce, инструментов сильно меньше, чем у OpenAPI.

API Blueprint. От Apiary (тоже куплены Oracle). Пишешь на упрощённом Markdown, получаешь спецификацию. Плюсы: приятно писать, понятно людям. Минусы: почти умер, Apiary давно не развивается, экосистема — маленькая.

gRPC + Protobuf. Не альтернатива в лоб, а другой подход. Плюсы: бинарный протокол — быстрее и компактнее, чем JSON; типизация сильнее; на нём удобно делать серверные и клиентские стримы. Минусы: не работает из браузера напрямую (нужен gRPC-Web-шлюз), сложнее отлаживать (бинарь нельзя прочитать глазами), не выйдет просто ткнуть в него из curl'а.

GraphQL + SDL. Тоже другой подход. Плюсы: один эндпоинт, клиент сам решает, какие поля запрашивать — не нужно делать десять разных методов «дай мне пользователя без адресов». Минусы: сложнее кэшировать (HTTP-кэши не понимают GraphQL), сложнее с авторизацией на уровне полей, тяжелее выучить.

AsyncAPI. Не конкурент, а сосед: тот же принцип, только для событийных систем (Kafka, RabbitMQ, WebSocket). Родственная спецификация — тот же YAML, похожая структура. Если у тебя стриминг событий и запрос-ответ одновременно — держишь оба файла.

Когда НЕ стоит использовать

Связанные понятия

Литература и источники

Где встретилось у меня

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

Краткое резюме