Документация API: OpenAPI и Swagger для бизнеса

Коротко. Документация API — описание того, как программы обмениваются данными с вашим сервисом. Стандарт де-факто — спецификация OpenAPI в YAML/JSON, а Swagger — инструменты вокруг неё: редактор, интерактивная страница, генератор кода. Бизнесу она сокращает сроки интеграций, онбординг разработчиков и зависимость от подрядчика.

По данным отчёта Postman State of the API 2025 (опрос более 5 700 разработчиков, архитекторов и руководителей), 93% API-команд сталкиваются с проблемами в совместной работе, и самая частая из них — несогласованная документация: на неё жалуются 55% опрошенных. Индустрия давно договорилась, как это лечить: документация API на OpenAPI/Swagger — машиночитаемая спецификация, которую развивает OpenAPI Initiative, плюс инструменты Swagger, которые превращают её в интерактивную страницу и готовый код. Вопрос лишь в том, внедрена ли эта практика у вас.

Для бизнеса отсутствие документации выглядит не как техническая мелочь, а как сорванные сроки. Интеграция с партнёром стопорится на неделю, потому что никто не может объяснить формат ответа. Мобильная команда ждёт бэкенд, вместо того чтобы работать параллельно. А знания о том, как устроен API, живут в голове одного разработчика — и уходят вместе с ним. Поэтому при разработке API на заказ мы сдаём спецификацию OpenAPI вместе с кодом: это такой же актив компании, как исходники.

В статье разберём, что такое документация API простыми словами, чем OpenAPI отличается от Swagger, как устроена спецификация, какой подход выбрать — design-first или code-first, какие инструменты использовать, что нового в OpenAPI 3.2 и почему документация вдруг стала важна для AI-агентов. В конце — пошаговый план внедрения, типичные ошибки и чек-лист того, что требовать от подрядчика.

Что такое документация API простыми словами

Документация API — это описание того, как другие программы могут обращаться к вашему сервису: какие запросы он принимает, какие данные возвращает, как проходит авторизация и что происходит при ошибке. API (Application Programming Interface) — это «дверь» в вашу систему для чужого кода, а документация — инструкция к этой двери.

Удобная аналогия — меню в ресторане. Гость не идёт на кухню выяснять, что умеет повар: он открывает меню, видит блюда, состав и цену и делает заказ в понятном формате. Документация API работает так же: разработчик мобильного приложения или партнёрского сервиса не читает ваш исходный код, а смотрит в описание и отправляет правильный запрос. Без меню каждый заказ превращается в переговоры.

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

Кто читает документацию API

Ваши бэкенд-разработчики — чтобы помнить, как устроены собственные методы, и не ломать их при доработках.
Фронтенд- и мобильные команды — чтобы встраивать данные в интерфейс сайта и приложений.
Партнёры и клиенты — чтобы интегрировать свои системы с вашей: маркетплейсы, платёжные сервисы, CRM, службы доставки.
Тестировщики и аналитики — чтобы проверять поведение системы и писать требования.
AI-агенты и ассистенты — новые читатели, которые вызывают API сами, ориентируясь на машиночитаемое описание.

Какой бывает документация API

Справочник эндпоинтов (API reference) — полный перечень методов, параметров, схем данных и кодов ответов. Его обычно генерируют из спецификации OpenAPI.
Гайды и туториалы — объяснение сценариев: как получить токен, как создать заказ и оплатить его, как обработать вебхук.
Changelog — журнал изменений: что добавили, что устарело, что сломается в следующей версии.
Справочные разделы — лимиты запросов, форматы дат и валют, коды ошибок, политика версионирования.

В этой статье основное внимание — справочнику и спецификации OpenAPI, потому что именно они служат «единым источником истины», из которого вырастает всё остальное.

Документация как интерфейс для разработчика

Для пользователя продукта интерфейс — это экраны и кнопки, а для разработчика, который подключается к вашему сервису, интерфейс — это документация. Её удобство называют developer experience (DX), и проектировать его стоит так же внимательно, как пользовательский опыт: с понятной навигацией, единым языком терминов, быстрым путём от «впервые открыл» до «отправил первый успешный запрос».

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

Что такое OpenAPI и Swagger и в чём разница

OpenAPI — это открытый стандарт описания REST API в формате YAML или JSON, а Swagger — семейство инструментов для работы с этим стандартом. Спецификация OpenAPI отвечает на вопрос «что умеет API», инструменты Swagger — на вопрос «как это удобно показать, отредактировать и превратить в код». Так это формулирует и официальная документация Swagger.

Файл спецификации описывает все эндпоинты, их параметры, схемы запросов и ответов, способы авторизации и метаданные. Его читают и люди, и программы: по одному и тому же файлу можно построить интерактивную документацию, мок-сервер, автотесты и клиентские библиотеки на десятке языков.

Краткая история: от Swagger к OpenAPI

Swagger появился в 2011 году как внутренний инструмент для описания API, быстро стал популярным и превратился в отраслевой стандарт. В 2015 году спецификацию передали в новую OpenAPI Initiative под эгидой Linux Foundation, а в 2016-м переименовали в OpenAPI Specification (Wikipedia). Название Swagger осталось за набором инструментов.

Версия	Год	Что изменилось
Swagger 1.x	2011	первая версия формата и инструментов
Swagger 2.0	2014	зрелый формат, ставший отраслевым стандартом; именно его передали OpenAPI Initiative
OpenAPI 3.0	2017	новая структура документа: раздел `components`, несколько серверов, улучшенное описание тел запросов и колбэков
OpenAPI 3.1	2021	полная совместимость с JSON Schema, вебхуки на верхнем уровне, необязательный раздел `paths`
OpenAPI 3.2	сентябрь 2025	иерархические теги, метод QUERY, описание стриминга, OAuth 2.0 Device Authorization Flow

Частое заблуждение: Swagger ≠ OpenAPI

Фразы «у нас есть сваггер» и «у нас есть спецификация OpenAPI» в разговорах обычно означают одно и то же, но для заказчика разница важна. Страница Swagger UI на тестовом стенде — это только витрина. Ценность — в файле спецификации, который лежит в репозитории, проверяется в CI и переживёт смену инструментов.

Критерий	OpenAPI	Swagger
Что это	спецификация, формат описания API	набор инструментов вокруг спецификации
Кто развивает	OpenAPI Initiative (Linux Foundation)	SmartBear и open-source-сообщество
Форма	файл `openapi.yaml` или `openapi.json`	Swagger Editor, Swagger UI, Swagger Codegen, платные продукты
Можно ли заменить	это стандарт, его не меняют — переходят между версиями	да: Redoc, Scalar, Stoplight, Postman и другие работают с той же спецификацией
Что требовать от подрядчика	файл спецификации в репозитории	опубликованную интерактивную документацию на стенде

Зачем документация API нужна бизнесу

Документация API — это инструмент, который сокращает время и деньги на любую работу с вашей системой: от подключения партнёра до смены подрядчика. В отчёте Postman документирование названо одной из трёх главных активностей API-команд: тестированием занимаются 81% разработчиков, разработкой — 73%, документированием — 58%. А 69% разработчиков тратят на работу с API больше 10 часов в неделю. Когда документации нет, часть этих часов уходит на расспросы и раскопки кода.

Команда согласует контракт API между мобильным приложением, сайтом и сервером

Быстрее интеграции и параллельная разработка

Когда контракт API зафиксирован в спецификации до написания кода, бэкенд, веб-фронтенд и мобильные приложения стартуют одновременно. Клиентские команды работают с мок-сервером, который отвечает по спецификации, а бэкенд реализует ту же спецификацию. К моменту интеграции стороны уже договорились о каждом поле — остаётся заменить мок на настоящий адрес.

Особенно это заметно в мобильной разработке: если вы планируете заказать мобильное приложение, спецификация API позволит iOS- и Android-командам стартовать параллельно с бэкендом, а не ждать его несколько спринтов. Подробнее о том, каким должен быть API для мобильного клиента, мы писали в статье «API для мобильного приложения».

Онбординг новых разработчиков и смена подрядчика

Новый разработчик с хорошей документацией разбирается в API за дни, без неё — за недели, отвлекая коллег вопросами. То же касается смены подрядчика: если у вас на руках только код без описания, новая команда сначала проводит «археологию» — и вы оплачиваете её часы.

Спецификация OpenAPI снижает зависимость от конкретных людей и компаний (vendor lock-in). Знания о системе перестают быть устными и становятся документом, который принадлежит вам. Поэтому документацию стоит включать в договор и в акт приёмки наравне с исходным кодом.

Партнёры и монетизация API

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

Даже если вы не продаёте доступ к API напрямую, интеграции с маркетплейсами, банками, логистикой и CRM подписываются быстрее, когда вы можете отправить партнёру ссылку на документацию вместо созвона с разработчиком.

Меньше ошибок и дешевле поддержка

Машиночитаемая спецификация позволяет автоматически проверять, что сервис отвечает именно так, как обещает: это называется контрактным тестированием. Расхождение между кодом и документацией ловится в CI до релиза, а не в виде жалобы от партнёра в пятницу вечером.

Отчёт Postman отмечает, что корень проблем часто не в отсутствии документации, а в её разбросанности: часть описания в вики, часть в чатах, часть в почте. Единый файл спецификации в репозитории убирает этот хаос — и вместе с ним бесконечную переписку «а какое тут поле обязательное?».

Как устроена спецификация OpenAPI

Спецификация OpenAPI — это структурированный документ, в котором каждый раздел верхнего уровня отвечает за свою часть описания API. Знать устройство файла полезно не только разработчикам: менеджер проекта по нему быстро оценит, насколько полно описан API, а заказчик — что именно ему передают.

Объект	Что описывает	Пример содержимого
`openapi`	версию спецификации	`3.1.0`
`info`	название, версию API, описание, контакты, лицензию	«Orders API, версия 1.4.0»
`jsonSchemaDialect`	диалект JSON Schema по умолчанию (с версии 3.1)	ссылка на диалект OpenAPI
`servers`	адреса окружений	прод, тестовый стенд, песочница
`paths`	эндпоинты и HTTP-методы с параметрами и ответами	`GET /orders/{id}`, `POST /orders`
`webhooks`	исходящие уведомления, которые API отправляет клиенту	«заказ оплачен», «статус доставки изменился»
`components`	переиспользуемые схемы, параметры, ответы, схемы безопасности	модель `Order`, стандартный ответ об ошибке
`security`	требования к авторизации по умолчанию	Bearer-токен, OAuth 2.0, API-ключ
`tags`	группировка методов в документации	«Заказы», «Клиенты», «Платежи»
`externalDocs`	ссылки на внешние руководства	портал разработчика, гайды

Минимальный пример на YAML

Ниже — короткий фрагмент спецификации: один метод получения заказа по идентификатору с двумя вариантами ответа. В реальном проекте таких методов десятки, но устроены они одинаково.

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{id}:
    get:
      summary: Получить заказ по ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Заказ найден
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404':
          description: Заказ не найден
components:
  schemas:
    Order:
      type: object
      properties:
        id: { type: string }
        status: { type: string, enum: [new, paid, shipped] }
        total: { type: number }

openapi и info — версия формата и паспорт API: название и версия самого сервиса.
paths → /orders/{id} → get — эндпоинт и HTTP-метод; фигурные скобки обозначают параметр пути.
parameters — параметр id обязателен, передаётся в пути и имеет тип «строка».
responses — что вернёт сервер: код 200 с объектом заказа или 404, если заказа нет.
$ref — ссылка на схему из components: модель Order описана один раз и переиспользуется во всех методах.
enum — допустимые значения статуса; клиент заранее знает, какие статусы бывают, и не гадает по реальным ответам.

Уже этот фрагмент Swagger UI превратит в страницу, где метод можно вызвать прямо из браузера, а OpenAPI Generator — в клиентскую библиотеку с готовым классом Order.

Design-first или code-first: какой подход выбрать

Design-first — это подход, при котором сначала проектируют и согласуют спецификацию API, а потом пишут код по ней. Code-first — обратный порядок: сначала код, а спецификацию генерируют из него с помощью аннотаций и библиотек. Оба подхода рабочие, вопрос в том, кто и когда пользуется API.

Критерий	Design-first	Code-first
Порядок работ	спецификация → ревью → код	код → генерация спецификации
Скорость старта	медленнее на первом этапе: нужно согласовать контракт	быстрее: разработчики сразу пишут код
Риск расхождения с кодом	есть, если не проверять соответствие в CI	минимальный, но описания полей часто остаются пустыми
Параллельная работа команд	да: фронтенд и мобайл работают с моком с первого дня	ограниченно: клиенты ждут, пока появится код
Качество API для потребителя	выше: контракт обсуждают до реализации	зависит от дисциплины команды
Подходит для публичных и партнёрских API	да, рекомендуемый вариант	возможно, но потребуется доработка описаний
Подходит для внутренних сервисов	да, если сервис используют несколько команд	да, особенно для небольших сервисов одной команды

Индустрия заметно смещается к design-first и более широкому подходу API-first, когда API проектируют как продукт ещё до интерфейсов. По данным Postman, 82% организаций в той или иной мере придерживаются API-first, а полностью — 25%, на 12 процентных пунктов больше, чем годом ранее.

Наша практика в YuSMP Group такая: для интеграций с партнёрами и проектов с мобильными приложениями выбираем design-first — контракт согласуем на этапе проектирования, и все команды стартуют одновременно. Для внутренних сервисов одной команды используем code-first с генерацией спецификации и обязательной проверкой в CI. Компромиссный вариант тоже возможен: начать с кода, сгенерировать спецификацию и дальше развивать её как первичный документ.

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

Инструменты документации API — это программы, которые помогают писать спецификацию OpenAPI, показывать её людям в удобном виде и превращать в код и тесты. Классический набор — инструменты Swagger, но экосистема давно шире, и выбирать стоит под задачу.

Swagger Editor

Swagger Editor — редактор спецификаций в браузере: слева YAML, справа живой предпросмотр документации. Он подсвечивает синтаксические ошибки и помогает быстро набросать контракт на этапе проектирования. Для командной работы файл всё равно лучше хранить в репозитории и редактировать в IDE с плагином OpenAPI.

Swagger UI

Swagger UI — самый известный способ показать документацию: интерактивная страница со списком методов, схемами и кнопкой «Try it out», которая отправляет реальный запрос к API. Его встраивают в приложение или разворачивают отдельно — например, на тестовом стенде, в Docker-контейнере или как статическую страницу.

Swagger Codegen и OpenAPI Generator

Генераторы кода создают по спецификации клиентские библиотеки (SDK) и серверные заглушки на десятках языков. Swagger Codegen — исходный инструмент, OpenAPI Generator — его популярный community-форк с широким набором шаблонов. Для бизнеса это экономия: мобильная команда получает готовый слой работы с API вместо ручного написания моделей и запросов, а партнёру можно выдать SDK.

Альтернативы: Redoc, Scalar, Stoplight, Postman

Спецификация OpenAPI не привязана к Swagger, поэтому вокруг неё выросло много инструментов. Ниже — те, что чаще всего встречаются в проектах.

Инструмент	Для чего	Модель	Когда выбрать
Swagger UI	интерактивная документация с вызовом методов	open source	внутренние API, тестовые стенды, быстрый старт
Redoc	читаемая трёхколоночная документация	open source, есть коммерческая платформа Redocly	публичная документация для партнёров
Scalar	современная интерактивная документация и API-клиент	open source, есть платные функции	портал разработчика с упором на удобство
Stoplight	визуальное проектирование API, стайлгайды, порталы	коммерческий, есть open-source-компоненты (Spectral, Prism)	design-first в большой команде
Postman	коллекции запросов, тесты, моки, публикация документации	бесплатный тариф и платные планы	ручное и автоматическое тестирование, совместная работа
OpenAPI Generator	генерация SDK и серверных заглушек	open source	несколько клиентов, партнёрские SDK
Spectral	линтинг спецификаций по правилам стиля	open source	контроль качества документации в CI

Генерация спецификации из кода по стекам

Если вы идёте по пути code-first или документируете уже существующий API, для каждого популярного стека есть библиотека, которая строит спецификацию OpenAPI из кода. Простыни настроек здесь не нужны — важно знать, что выбор есть почти везде.

Стек	Библиотека	Комментарий
Java / Spring Boot	springdoc-openapi	спецификация по контроллерам и аннотациям, встроенный Swagger UI
Python / FastAPI	встроено во фреймворк	спецификация строится по типам и моделям Pydantic автоматически
Node.js / Express	swagger-jsdoc	описание в JSDoc-комментариях к маршрутам
Node.js / NestJS	@nestjs/swagger	декораторы на контроллерах и DTO
PHP / Laravel	L5-Swagger	аннотации или атрибуты PHP, Swagger UI из коробки
.NET / ASP.NET Core	Swashbuckle, Microsoft.AspNetCore.OpenApi	встроенная поддержка OpenAPI в новых версиях платформы (Microsoft Learn)
Go	swaggo/swag	генерация по комментариям к обработчикам

Во всех случаях автогенерация даёт каркас: пути, методы и типы. Описания полей, примеры значений и сценарии ошибок команда дописывает сама — и именно они отличают полезную документацию от формальной.

Что нового в OpenAPI 3.2 и стоит ли переходить

OpenAPI 3.2 — это первое минорное обновление спецификации после версии 3.1, выпущенное OpenAPI Initiative в сентябре 2025 года. Об изменениях подробно рассказано в анонсе OpenAPI v3.2, а полный текст опубликован на spec.openapis.org. Главное:

Иерархические теги. У тегов появились поля summary, parent и kind: методы можно группировать во вложенные разделы, а не в один плоский список. Для больших API это заметно упрощает навигацию по документации.
Метод QUERY и additionalOperations. Спецификация поддерживает HTTP-метод QUERY — безопасный запрос с телом, удобный для сложных поисковых фильтров. А additionalOperations позволяет описать и другие нестандартные методы.
Стриминг. Появилось описание потоковых ответов: Server-Sent Events, JSON Lines, JSON Sequences, multipart/mixed, а также поле itemSchema для схемы отдельного элемента потока. Это важно для чатов, уведомлений и ответов языковых моделей, которые приходят по частям.
OAuth 2.0 Device Authorization Flow. Поддержка авторизации для устройств без удобного ввода — телевизоров, консолей, IoT.
oauth2MetadataUrl. Ссылка на метаданные сервера авторизации, чтобы клиенты получали настройки OAuth автоматически.

Стоит ли переходить? Для новых проектов разумно начинать с 3.1 и переходить на 3.2, когда её поддержат ваши генераторы, линтеры и средства отображения — поддержка в инструментах появляется постепенно, и это стоит проверить для своего набора перед стартом. Миграция с 3.0 не срочна: спецификации 3.0 продолжают работать во всех популярных инструментах. Переход окупается, когда нужны конкретные возможности — например, стриминг или вложенные теги для большого API.

Документация API для AI-агентов и MCP

Документация API для AI-агентов — это машиночитаемое описание, по которому языковая модель может сама понять, какой метод вызвать, с какими параметрами и как интерпретировать ответ. Если раньше документацию читали только люди, то теперь её читают и программы на основе ИИ — ассистенты, агенты, IDE-помощники.

Отчёт Postman фиксирует разрыв: 89% разработчиков уже используют генеративный ИИ в работе, но лишь 24% проектируют API с учётом AI-агентов. При этом 41% применяют ИИ для генерации документации API. То есть ИИ активно пишет документацию, но мало кто готовит API к тому, что его будут вызывать агенты.

Почему агентам нужна именно хорошая спецификация:

Агент не может переспросить коллегу. Всё, что не описано в спецификации, для него не существует, а то, что описано двусмысленно, он поймёт как угодно.
Типизированные ошибки помогают восстанавливаться. Если ответ 409 описан как «заказ уже оплачен», агент выберет другое действие, а не будет повторять запрос.
Примеры важнее прозы. Конкретные примеры запросов и ответов снижают число ошибок при вызове методов.
Описания методов — это подсказки для выбора. Модель выбирает инструмент по его описанию, поэтому «GET /items» без пояснений проигрывает «Поиск товаров каталога по названию и категории».

MCP (Model Context Protocol) — открытый протокол, через который AI-ассистенты подключаются к внешним инструментам и данным. MCP-серверы для существующих сервисов часто строятся поверх API и их описаний, поэтому качественная спецификация OpenAPI заметно ускоряет подключение вашего продукта к AI-экосистеме.

Одно предостережение: ИИ отлично пишет черновики описаний, но может уверенно выдумать поле, ограничение или код ошибки. Документацию, сгенерированную ИИ, обязательно проверяет человек, а лучше — автоматические контрактные тесты.

Как внедрить документацию API: пошагово

Внедрение документации API — это не разовая задача «написать описание», а настройка процесса, при котором документация создаётся и обновляется вместе с кодом. Мы проводим его в восемь шагов:

Проведите инвентаризацию эндпоинтов и потребителей. Соберите список всех методов API, в том числе недокументированных и устаревших, и выясните, кто их вызывает: веб-фронтенд, мобильные приложения, партнёры, внутренние сервисы. Это покажет, с чего начинать и какие методы нельзя ломать.
Выберите подход и версию спецификации. Для новых API и интеграций с внешними командами выбирайте design-first, для существующего кода — генерацию спецификации из кода с последующей доработкой описаний. Версию OpenAPI выбирайте с оглядкой на поддержку в ваших инструментах: для новых проектов обычно это 3.1.
Опишите контракт. Зафиксируйте пути и методы, параметры, схемы запросов и ответов, коды ошибок, способы авторизации и примеры. Повторяющиеся модели вынесите в components, чтобы не копировать их по всему файлу.
Настройте линтинг и правила стиля. Подключите линтер спецификаций, например Spectral, и задайте правила: единый стиль имён, обязательные описания и примеры, описанные ошибки. Линтер ловит пропуски до того, как их увидит потребитель API.
Опубликуйте интерактивную документацию и мок-сервер. Разверните Swagger UI, Redoc или Scalar на тестовом стенде или в портале разработчика и поднимите мок-сервер по спецификации. Фронтенд и мобильные команды смогут работать до готовности бэкенда.
Встройте спецификацию в CI/CD. Добавьте в пайплайн проверку соответствия кода спецификации, контрактные тесты, поиск ломающих изменений и генерацию клиентских SDK. Тогда документация не сможет незаметно отстать от кода.
Введите версионирование и changelog. Договоритесь, что считается ломающим изменением, как обозначаются версии и как долго поддерживается старая версия. Каждое изменение контракта фиксируйте в changelog, понятном потребителям.
Назначьте владельца документации. У документации должен быть конкретный ответственный — обычно техлид или архитектор API. Он принимает изменения контракта, следит за качеством описаний и отвечает на вопросы потребителей.

Самые недооценённые шаги — шестой и восьмой. Без проверки в CI документация начинает устаревать с первого же релиза, а без владельца никто не замечает, что она устарела. Если в архитектуре есть шлюз, спецификации удобно использовать и для его настройки — об этом подробнее в статье «Что такое API Gateway и зачем он нужен».

Типичные ошибки в документации API

Типичные ошибки документации API — это пробелы, из-за которых документ формально существует, но пользоваться им нельзя. Чаще всего при аудите мы находим следующее:

Документация живёт отдельно от кода. Описание лежит в вики или в Word-файле, его обновляют «когда будет время» — и через пару релизов оно перестаёт совпадать с реальностью.
Нет примеров запросов и ответов. Схема данных есть, а живого примера нет, и разработчик клиента гадает, в каком формате передавать дату или сумму.
Не описаны ошибки. Документирован только успешный ответ 200, а что значат 400, 409 или 422 и как их обрабатывать, приходится выяснять опытным путём.
Нет описания авторизации и лимитов. Непонятно, как получить токен, сколько он живёт и сколько запросов в минуту можно отправить до блокировки.
Разбросанность по вики, чатам и почте. Часть договорённостей в переписке, часть в задачах, часть в головах. Отчёт Postman прямо называет это корнем проблем: нужен единый источник истины.
Ломающие изменения без новой версии. Поле переименовали или сделали обязательным «тихо» — и мобильные приложения у пользователей, которые ещё не обновились, перестают работать.
Только автогенерация без описаний. Спецификация есть, но поля называются flag, type2 и data без единого пояснения. Формально документация существует, фактически нет.
Нет changelog. Потребители узнают об изменениях из упавших интеграций, а не из уведомления.

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

Что требовать от подрядчика: чек-лист документации API

Чек-лист документации API — это список артефактов, которые заказчик вправе требовать при приёмке любого проекта с API. Его стоит включить в ТЗ и договор заранее, а не вспоминать о нём на этапе сдачи. При приёмке проверьте:

☐ файл спецификации OpenAPI лежит в репозитории проекта рядом с кодом;
☐ описаны все эндпоинты, включая служебные и административные;
☐ у каждого поля есть тип, описание и признак обязательности;
☐ описаны коды ошибок и формат ответа об ошибке;
☐ описаны авторизация, сроки жизни токенов и лимиты запросов;
☐ у ключевых методов есть примеры запросов и ответов;
☐ интерактивная документация (Swagger UI, Redoc или аналог) опубликована на тестовом стенде;
☐ соответствие кода спецификации проверяется в CI;
☐ есть changelog и правила версионирования;
☐ документация явно входит в акт приёмки работ;
☐ права на документацию принадлежат заказчику, как и права на код.

Если часть пунктов не выполнена, это не обязательно повод для конфликта — но точно повод договориться о доработке до подписания акта. После подписания стоимость восстановления документации ляжет на вас. Чтобы требования к API были зафиксированы с самого начала, их удобно прописать в техническом задании — см. наш разбор «ТЗ на разработку мобильного приложения: как написать».

Сколько времени занимает документация

Трудозатраты на документацию сильно зависят от того, когда о ней вспомнили. По нашему опыту, ориентиры такие:

Design-first в новом проекте. Спецификация создаётся на этапе проектирования и не требует отдельного бюджета: время на неё окупается за счёт параллельной работы команд и меньшего числа переделок при интеграции.
Code-first в новом проекте. Генерация настраивается один раз, дальше основные затраты — на описания полей и примеры, которые разработчики пишут вместе с кодом.
Существующий API без документации. Нужен аудит: инвентаризация методов, генерация черновика спецификации, сверка с реальным поведением и дописывание описаний. Объём работ зависит от числа эндпоинтов и качества кода, поэтому оценку мы даём после аудита.

Общее правило простое: документация, встроенная в процесс с первого дня, почти ничего не стоит. Документация, которую восстанавливают через три года по коду, стоит дорого — и всегда дороже, чем казалось.

Найдем лучшее решение для вас

Частые вопросы о документации API (FAQ)

Swagger и OpenAPI — это одно и то же?

Нет. OpenAPI — это открытая спецификация, то есть формат описания REST API в YAML или JSON, которую развивает OpenAPI Initiative под эгидой Linux Foundation. Swagger — набор инструментов вокруг этой спецификации: Swagger Editor, Swagger UI, Swagger Codegen. Путаница возникла исторически: до 2016 года сама спецификация тоже называлась Swagger.

Чем OpenAPI 3.0, 3.1 и 3.2 отличаются?

Версия 3.0 (2017) задала современную структуру спецификации с разделом components. Версия 3.1 (2021) стала полностью совместимой с JSON Schema и добавила вебхуки. Версия 3.2 (сентябрь 2025) принесла иерархические теги, метод QUERY, описание стриминговых ответов и OAuth 2.0 Device Authorization Flow. Для большинства новых проектов сегодня разумный выбор — 3.1, а на 3.2 переходят по мере поддержки в инструментах.

Можно ли сгенерировать документацию API автоматически из кода?

Да, для большинства стеков есть библиотеки, которые строят спецификацию OpenAPI по коду и аннотациям: springdoc-openapi для Spring, встроенная генерация в FastAPI, @nestjs/swagger для NestJS, Swashbuckle и Microsoft.AspNetCore.OpenApi для .NET. Но автогенерация даёт только скелет: описания полей, примеры и сценарии ошибок всё равно пишут люди.

Подходит ли OpenAPI для GraphQL и gRPC?

Нет, OpenAPI описывает REST- и HTTP-API. У GraphQL свой контракт — схема на языке SDL и интроспекция, у gRPC — файлы .proto. Для асинхронных API на брокерах сообщений и событиях используют родственную спецификацию AsyncAPI. Если в системе несколько типов API, у каждого должен быть свой машиночитаемый контракт. Как выбрать между подходами, мы разбирали в статьях «REST vs GraphQL» и «gRPC vs REST: что выбрать».

Нужна ли документация для внутреннего API, которым пользуется только своя команда?

Нужна. Внутренний API тоже переживает смену разработчиков, рост команды и появление новых клиентов — мобильного приложения, партнёрского сервиса, AI-ассистента. Минимум — спецификация OpenAPI в репозитории, которая генерируется или проверяется в CI. Это дешевле, чем каждый раз восстанавливать знания по коду и чатам.

Как держать документацию в актуальном состоянии?

Хранить спецификацию в том же репозитории, что и код, и проверять её в CI/CD: линтером, контрактными тестами и поиском ломающих изменений. Изменение API без изменения спецификации не должно проходить ревью. Ещё помогает назначенный владелец документации и changelog, который обновляется с каждым релизом.

Можно ли использовать ИИ для написания документации API?

Можно, и многие так делают: по данным Postman, 41% разработчиков используют ИИ для генерации документации API. ИИ хорошо справляется с черновиками описаний, примерами и переводом. Но результат обязательно проверяет человек: модель может придумать несуществующие поля, коды ошибок или ограничения, а ошибка в контракте обходится дороже, чем её отсутствие.

Документация API: OpenAPI/Swagger и зачем она нужна бизнесу