Swagger и OpenAPI: как задокументировать свой API без рук

Ты попросил ИИ-ассистента собрать API для своего приложения — что это вообще такое, разобрано в отдельной статье. Всё заработало: игра отправляет рекорды, сервер их сохраняет, список лучших игроков подгружается на экран. Через месяц ты возвращаешься к проекту, чтобы добавить новую фичу, и не можешь вспомнить, какой метод принимает /scores — POST или PUT, обязательно ли поле player_name и что вернётся, если очков передать отрицательное число. Код где-то это знает, но читать весь файл сервера ради одного эндпоинта неудобно. Ещё хуже, если API нужно показать другому человеку или подключить к стороннему сервису: пересказывать структуру запросов вручную — плохая идея, там легко ошибиться или забыть деталь. Для этой задачи придуман стандарт OpenAPI и набор инструментов Swagger вокруг него — разберём, что это, чем они отличаются друг от друга и как получить документацию, вообще не садясь писать её руками. Заодно посмотрим на живой фрагмент такой спецификации и попробуем её в интерактивной странице, чтобы термины не остались абстракцией.

OpenAPI и Swagger — в чём разница простыми словами

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

OpenAPI — открытый стандарт, который описывает, как записать структуру REST API в один файл: какие есть адреса, какие методы у каждого из них, что принимает запрос, что возвращает ответ, какие бывают ошибки. Файл пишется в YAML или JSON — тех же форматах, в которых хранятся данные при обмене между приложениями. Стандарт развивает некоммерческая организация OpenAPI Initiative, и он не привязан ни к одному конкретному инструменту: спецификацию, написанную по правилам OpenAPI, поймёт любая программа, которая умеет с ней работать.

Swagger — исходное название всего проекта, из которого вырос стандарт OpenAPI. Компания SmartBear, которая сейчас развивает Swagger, в какой-то момент передала сам формат описания API в открытую организацию, и он стал называться OpenAPI: старые файлы версии 2.0 ещё называют «Swagger-спецификацией», а всё, что написано под текущий OpenAPI 3.0, — уже «OpenAPI-спецификацией», хотя по сути это один и тот же формат на разных этапах его истории. Имя Swagger при этом осталось за набором конкретных инструментов, которые с этим форматом работают: Swagger Editor — для написания и проверки спецификации, Swagger UI — для показа готовой документации в браузере, Swagger Codegen — для генерации кода клиента по спецификации.

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

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

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

Спецификация OpenAPI — это обычный текстовый файл, который принято называть openapi.yaml или openapi.json. YAML читается человеком чуть легче, JSON — тот же самый набор данных, только в других скобках; оба формата взаимозаменяемы, и инструменты вроде Swagger Editor умеют конвертировать один в другой одной кнопкой. Разбираться в полном синтаксисе не нужно — вполне достаточно понимать общую форму, чтобы при случае прочитать чужую спецификацию или узнать в сгенерированном файле знакомые части своего API.

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

openapi: 3.0.3
info:
  title: API Змейки
  version: 1.0.0
paths:
  /scores:
    get:
      summary: Получить список рекордов
      responses:
        "200":
          description: Список рекордов
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Score"
    post:
      summary: Сохранить результат игры
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [player_name, score]
              properties:
                player_name:
                  type: string
                score:
                  type: integer
      responses:
        "201":
          description: Рекорд сохранён
        "400":
          description: Неверные данные в запросе
components:
  schemas:
    Score:
      type: object
      properties:
        id:
          type: integer
        player_name:
          type: string
        score:
          type: integer
        created_at:
          type: string
          format: date-time

Первая строка openapi: 3.0.3 — номер версии стандарта. Сейчас в ходу линейка OpenAPI 3.0, и почти все современные инструменты и генераторы ориентируются именно на неё, поэтому если в чужом проекте или сгенерированной документации встретится эта строка — можно быть уверенным, что читаешь актуальный формат, а не устаревший Swagger 2.0 из более ранних лет. Дальше info — общее название и версия самого API, не путать с версией стандарта. Раздел paths — сердце файла: под каждым адресом перечислены методы, которые он поддерживает, а под каждым методом — что ожидается в requestBody и что вернётся в responses по каждому возможному статус-коду.

Отдельного внимания заслуживает раздел components. Если бы структура рекорда описывалась заново под каждым методом, файл быстро раздулся бы и разошёлся сам с собой — где-то поле назвали score, а где-то по ошибке points. Вместо этого структуру описывают один раз под именем Score в components/schemas, а из paths на неё просто ссылаются через $ref. Тот же приём используют для повторяющихся параметров запроса или заголовков авторизации: описал один раз, сослался в нужных местах.

Кроме тела запроса, спецификация умеет описывать и параметры прямо в адресе. Если бы понадобился эндпоинт для удаления конкретного рекорда, DELETE /scores/{id}, часть с фигурными скобками объявляется как parameters с in: path — так инструмент понимает, что {id} нужно заменить на настоящее число, а не оставлять как есть. Похожим образом описываются query-параметры вроде ?limit=10 для ограничения выдачи — только с in: query вместо in: path. Отдельный раздел security нужен, если эндпоинт требует авторизации: там указывается, что именно сервер ожидает — например, заголовок Authorization с токеном пользователя. Swagger UI при этом сам добавляет на странице документации поле для ввода такого токена, чтобы «Try it out» отправлял запросы уже с ним.

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

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

Swagger UI — документация, которую можно потыкать в браузере

Сама по себе спецификация OpenAPI — это просто текстовый файл, и читать его построчно так же удобно, как читать JSON-ответ сервера без форматирования: технически возможно, но никакого удовольствия. Swagger UI решает именно эту проблему: он берёт файл спецификации и превращает его в обычную веб-страницу со списком эндпоинтов, разворачивающимися блоками с параметрами и примерами ответов.

Главное, что отличает Swagger UI от простого текстового описания API, — кнопка «Try it out». На странице документации можно раскрыть нужный эндпоинт, ввести значения прямо в поля формы и отправить настоящий запрос к серверу, не открывая ни Postman, ни консоль браузера. Ответ придёт туда же, на этой странице, со статус-кодом и телом ответа — точно так, как если бы запрос отправило само приложение. Для отладки это удобнее, чем собирать запрос вручную: поля, типы данных и обязательность параметров уже подставлены из спецификации, ошибиться в написании адреса или названия поля почти невозможно.

Разворачивается Swagger UI обычно прямо рядом с самим API — как отдельный маршрут вроде /docs или /api-docs, который сервер отдаёт наравне с остальными. При каждом запуске он читает файл спецификации и строит страницу заново, так что документация не расходится с реальным API, если её вовремя обновлять при изменении кода. Есть и вариант без своего сервера вообще: на сайте editor.swagger.io спецификацию можно вставить прямо в браузер и мгновенно увидеть, как она выглядит в виде интерактивной документации — удобно, если нужно быстро проверить синтаксис файла или показать API коллеге, не разворачивая ничего у себя.

Сама страница Swagger UI — это только оболочка поверх файла. Обычно рядом с /docs сервер отдаёт и сырой файл спецификации отдельно, например по адресу /docs/openapi.json или /openapi.yaml — это уже не картинка для человека, а тот же JSON или YAML, который можно скачать и передать в другую программу: генератор клиентского кода, коллекцию Postman, тесты. Разница между «показать человеку» и «отдать программе» в OpenAPI не требует двух разных файлов — один и тот же источник обслуживает оба случая, меняется только то, во что его превращает конкретный инструмент.

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

Как попросить ИИ-ассистента сгенерировать документацию

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

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

Ассистент разберёт код сервера, найдёт объявленные маршруты, посмотрит, какие поля читаются из тела запроса и что возвращается в ответ, и на основе этого соберёт спецификацию. Дальше он же поставит нужный пакет вроде swagger-ui-express, подключит его к серверу и укажет, что документация теперь доступна по конкретному адресу. Получившийся файл стоит один раз просмотреть — не с целью переписать вручную, а чтобы убедиться, что названия полей и типы данных совпадают с тем, что реально ожидает сервер, особенно если в коде есть проверки, которые не сразу очевидны из объявления маршрута.

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

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

Если проект растёт и маршрутов становится много, полезно попросить ассистента не только сгенерировать спецификацию с нуля, но и держать её актуальной по ходу работы — например, добавить в конец сессии короткую проверку: «Сверь openapi.yaml с текущим кодом сервера и допиши то, чего не хватает». Это дешевле, чем разбираться постфактум, какие три эндпоинта из пяти новых так и не попали в документацию. Для совсем маленького проекта такая проверка не нужна на каждом шаге — достаточно вспоминать про неё перед тем, как показать API кому-то ещё или отложить проект на паузу.

Зачем это даже маленькому учебному проекту

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

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

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

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

Есть и четвёртый случай, менее очевидный. Когда в проекте несколько эндпоинтов и они появлялись в разное время, легко потерять единообразие: один маршрут возвращает дату в формате 2026-08-18, другой — 18.08.2026, третий вообще без даты. Пока список маршрутов держится в голове, такие расхождения не бросаются в глаза. Собранные вместе на одной странице Swagger UI, они видны сразу — весь API как на ладони, и несостыковки в форматах полей находятся глазами за секунды, а не путём чтения кода каждого маршрута по отдельности.

Как попробовать OpenAPI и Swagger на практике

Проще всего почувствовать разницу между форматом и инструментом на трёх коротких шагах, без правки собственного проекта.

1. Открой готовую спецификацию в браузере. Зайди на editor.swagger.io и вставь фрагмент YAML из раздела выше — сразу увидишь справа сгенерированную страницу документации с эндпоинтами /scores, полем player_name и возможными ответами. Это и есть тот самый переход от текстового файла к интерактивной странице, который делает Swagger UI.
2. Попробуй «Try it out» на любом публичном API со Swagger-документацией. Многие сервисы держат свою документацию открытой по адресу вроде /docs или /swagger, и там же есть кнопка для тестового запроса. Заполнение полей формы вместо ручной сборки запроса — ровно та экономия времени, ради которой Swagger UI существует.
3. Попроси ИИ-ассистента сделать то же самое для своего проекта. Если API уже написан, промпт из раздела выше сгенерирует и спецификацию, и подключение Swagger UI за один запрос.
4. Открой результат у себя. После генерации ассистент обычно добавляет в код сервера несколько строк вроде этих (для Express-сервера на Node.js):

const swaggerUi = require("swagger-ui-express");
const YAML = require("yamljs");
const spec = YAML.load("./openapi.yaml");

app.use("/docs", swaggerUi.serve, swaggerUi.setup(spec));

Дальше достаточно открыть /docs на локальном сервере — увидишь тот же интерфейс, что и на editor.swagger.io, но уже со своими эндпоинтами вместо чужого примера, и с настоящей кнопкой «Try it out», которая обращается к твоему реальному серверу.

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

Частые ошибки при работе с OpenAPI и Swagger

Ошибка 1. Спецификация написана один раз и больше не обновляется

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

Ошибка 2. Путать формат и инструмент в разговоре с ассистентом

Просьба «сделай мне Swagger» и просьба «сгенерируй спецификацию OpenAPI и подключи Swagger UI» для человека звучат почти одинаково, но для точной постановки задачи вторая формулировка полезнее: она отдельно называет файл, который нужно создать, и отдельно — интерфейс, в котором его показать. Не критичная ошибка, современные ассистенты понимают и короткую версию, но чем конкретнее описан ожидаемый результат, тем меньше риск, что получится не совсем то, что имелось в виду.

Ошибка 3. Оставить Swagger UI открытым на боевом проекте без раздумий о доступе

Страница документации по умолчанию доступна всем, кто знает адрес /docs, и кнопка «Try it out» умеет отправлять настоящие запросы. Для учебного проекта или внутреннего API это обычно не проблема, но если сервер хранит данные реальных пользователей, стоит заранее решить, прятать ли документацию за тем же логином, что и сам API, или ограничивать её только локальной разработкой.

Ошибка 4. Верить сгенерированной спецификации без единой проверки

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

Чек-лист «документация API готова»

• Файл openapi.yaml (или .json) лежит в проекте и описывает все реальные маршруты сервера.
• Версия стандарта указана явно — openapi: 3.0.x, а не унаследованный формат Swagger 2.0.
• Swagger UI подключён по отдельному адресу вроде /docs и открывается без ошибок.
• Хотя бы один эндпоинт проверен через «Try it out» — ответ совпадает с тем, что описано в спецификации.
• Обязательные поля и типы данных в схемах соответствуют реальным проверкам на сервере.
• Решено, кому доступна страница документации — всем или только при разработке.
• Договорённость (с собой или с командой), что правка маршрута сопровождается правкой спецификации.

Частые вопросы

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

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

Обязательно ли писать спецификацию OpenAPI руками?

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

В каком формате хранить файл — YAML или JSON?

Разницы по содержанию нет: оба формата описывают одни и те же данные, просто в разной пунктуации, и инструменты вроде Swagger Editor конвертируют один в другой автоматически. YAML чуть легче читать человеку глазами, JSON удобнее, если файл собирается программой или передаётся между сервисами. Для ручной правки чаще выбирают YAML.

Подходит ли это для проекта на Supabase?

Да, но с оговоркой. Supabase сам генерирует REST-документацию по таблицам базы через встроенный интерфейс в панели проекта, и для стандартных операций с таблицами она уже есть без дополнительной настройки. OpenAPI и Swagger больше пригождаются для своих собственных серверных маршрутов — например, если рядом с Supabase есть отдельный Node.js-сервер с кастомной логикой, как в сценариях с Socket.io или другой серверной обработкой.

Безопасно ли открывать Swagger UI всем в интернете?

Стоит подумать заранее. Страница документации показывает структуру всех эндпоинтов, включая те, что не предназначены для посторонних глаз, и кнопка «Try it out» позволяет отправлять настоящие запросы к серверу. Для учебного проекта с публичными данными это не критично, но для API с чувствительной информацией документацию лучше держать за тем же уровнем доступа, что и сам API, а не выкладывать её отдельным открытым маршрутом.

Что делать, если сгенерированная спецификация не совпадает с реальным поведением сервера?

Такое случается, если код API написан непоследовательно — например, проверка обязательного поля есть, но в комментариях не отражена, и ассистент её не увидел. Достаточно открыть конкретный эндпоинт в Swagger UI, вызвать его через «Try it out» с разными данными и сверить реальный ответ с тем, что написано в документации. Расхождение — повод либо поправить спецификацию, либо, если дело в самом коде, сначала привести в порядок его логику.

Источники

1. Спецификация OpenAPI — официальный сайт инициативы: openapis.org
2. Swagger — официальный сайт инструментов: swagger.io
3. Онлайн-редактор Swagger Editor: editor.swagger.io

Заключение

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

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

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