Привет, Хабр! На связи Маргарита Сорочинская, технический писатель отдела архитектуры в Рунити. Хочу рассказать, как мы в компании подошли к описанию API в Swagger — и почему решили перенести туда всё, что раньше жило в Confluence. А еще поделюсь с вами стартерпаком для описания API в Swagger, пошаговой инструкцией и всеми ссылками, чтобы для вас этот путь был уже более простым :) 

Навигация по тексту:

• Всё API — в Swagger: эксперимент

• Стартерпак для описания API в Swagger

• Пишем структуру документа: что важно не упустить

• Пошаговая инструкция документирования и загрузки на Git

• Что изменилось после перехода

• Swagger без прикрас: где помог, а где усложнил

• Рекомендации для тех, кто только начинает

• Начали как эксперимент, а продолжаем как стандарт

Если коротко, всё началось с хаоса.
У нас давно была привычка документировать API в Confluence: это удобно, можно быстро вставить примеры, ссылки, комментарии. Но со временем документации становилось всё больше, и вместе с этим росла путаница.

У каждой команды — свой подход. Где-то Swagger велся и выглядел аккуратно, где-то просто существовал: методы генерировались автоматически, но без описаний. В Confluence могли лежать устаревшие данные, а в Swagger — актуальные, или наоборот. Разработчики, аналитики и тестировщики постоянно уточняли друг у друга: «А где правильная версия?», «Этот метод вообще еще жив?».

В какой-то момент стало очевидно: так дальше нельзя. Документация должна быть в одном месте и оставаться актуальной.

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

Всё API — в Swagger: эксперимент

Инициатива появилась не сверху, а внутри команды.
Однажды у нас возникла задача по проекту, где у разработчиков был довольно большой Swagger — с десятками методов. Часть из них была описана, но у многих не было ни параметров, ни пояснений. Еще больше методов вообще не фигурировало нигде: ни в Swagger, ни в Confluence.

Тогда мой коллега предложил попробовать описать всё целиком именно в Swagger. Мы не знали, насколько это трудоемко и оправдано, но решили провести эксперимент.

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

В процессе быстро стало ясно, что задача непростая. Многие методы приходилось описывать с нуля — добавлять summary, параметры, схемы ответов. Иногда это занимало по полчаса на один метод, особенно если структура была сложной.

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

Когда мы начали документировать методы, быстро выяснилось, что красивых схем из презентаций про Swagger в реальности не бывает.
Мы шли от кода — открывали GitLab-репозиторий проекта, брали файл swagger.yaml (или создавали openapi.yaml, если его не было), открывали его в VS Code и подключали к редактору editor.swagger.io.

Дальше всё по шагам: добавляем метаданные, описываем методы, прописываем параметры и схемы ответов, проверяем отображение в правой панели редактора. После этого правим файл и коммитим в Git.

Стартерпак для описания API в Swagger

Для документирования понадобятся следующие инструменты и сервисы:

• GitHub / GitLab

• Confluence

• Текстовый редактор (мы использовали VS Code)

• editor.swagger.io

Пишем структуру документа: что важно не упустить

Документ OAS 3.0 имеет структуру, состоящую из нескольких ключевых компонентов.
Интерактивная схема структуры лежит по ссылке. 

Очень коротко разберем ключевые компоненты.

В начале документа — метаданные и описание методов.

Шаблон для описания метода

get:                             # название запроса

    tags:                        # позволяет группировать эндпоинты

    summary:                     # краткое описание метода

    operationId:                 # метод контроллера, берется из rc-web-api/routes/api.php

    responses:                   # ответы

        200:                     # код ответа

            description:         # описание ответа

            content:             # указываем формат схемы

                application/json: # тип данных

                    schema:      # схема входных/выходных данных

В методах вы можете увидеть ссылки на компоненты.

Компоненты содержат описания, которые используются в разных запросах. Таким образом снижается дублирование кода и его количество.

Пример компонентов

В компонентах могут быть ссылки на описание схем (schemas) и параметров (parameters).
Схемы (schemas) содержат структуру данных тела запроса/ответа — отдельные классы с описанием параметров.

Шаблон для описания схемы

GetVersionResponse:              # наименование схемы ответа

    title:                       # название ответа на русском

    type:                        # тип объекта

    properties:                  # свойства объектов схемы

        version:                 # наименование объекта

            type:                # тип данных

            description:         # описание объекта

            example:             # пример

Пошаговая инструкция документирования и загрузки на Git

Документирование

Схема Swagger всегда где-то лежит — в нашем случае это GitLab. GitLab и будет нашей отправной точкой.

1. Заходим в GitLab проекта.

2. Находим и скачиваем файлы swagger.yaml и openapi.yaml.
   Если файла openapi.yaml нет — создаем.

3. Открываем файлы в редакторе кода (например, VS Code).

4. Открываем сервис https://editor.swagger.io/ и копируем в левую часть панели код из openapi.yaml (если файл пустой — из swagger.yaml).

5. Начинаем документировать с самого начала (см. раздел «Пишем структуру документа: что важно не упустить»).

6. Проверяем результат в правой части экрана editor.swagger.io.

7. Копируем и переносим код в openapi.yaml и сохраняем его.

Загрузка на Git

Получаем доступ к личной ветке у разработчиков или ответственных за доступы.

В командной строке вводим:

cd *путь до папки, где находится файл openapi.yaml

git add openapi.yaml

git commit -m "какой-то ваш комментарий"

git push

Для ускорения процесса можно использовать ChatGPT (если это допускается политикой безопасности) или готовый шаблон, например, из этой статьи.

Процесс казался простым, пока не дошло до объема. Многие методы приходилось описывать с нуля — без заготовок, без описаний. Иногда на один метод уходило до сорока минут: нужно было разобраться в параметрах, описать структуру тела запроса и ответа, указать примеры.

Так выглядел метод POST /app/v1/ext/auth до добавления описаний и примеров:

Ниже — схема с параметрами и пример запроса в JSON.

Параллельно мы учились работать с Git. Для технических писателей это не всегда привычная среда. У кого-то вызывала страх сама консоль: «а вдруг я что-то сломаю?». Но без этого никуда — Swagger-файлы живут в тех же ветках, что и код. Со временем привыкли: ошибки правили вручную, конфликты решали через редактирование строк в YAML.

Чтобы ускорить работу, мы использовали готовые шаблоны и, признаюсь честно, иногда проверяли себя через нейросети — генерировали примеры описаний и потом переписывали под реальные данные. Это помогало сэкономить время, но, конечно, не заменяло ручную работу.

Главный вывод после первых недель: документирование в Swagger требует времени, но результат стоит усилий. Файл живет рядом с кодом, обновляется вместе с ним и перестает быть «мертвой копией» из Confluence.

Что изменилось после перехода

После эксперимента стало заметно проще ориентироваться в документации.

Теперь, если нужно посмотреть, как работает конкретный метод, не приходится искать его между страницами Confluence и внутренними таблицами. Всё лежит в одном месте — в Swagger-файле рядом с кодом.

Для разработчиков это избавило от двойной работы: не нужно писать описание дважды.

Для аналитиков и архитекторов — снизило риск ошибок. Теперь они видят актуальные данные, могут быстро проверить структуру запроса или ответа и не сомневаться, какой вариант правильный.

Для технических писателей — стало меньше ручной рутины и копирования. Вместо «внести правку в двух местах» теперь просто обновляем схему и даем ссылку на нее.

Еще одно важное изменение — повысилась прозрачность.

Swagger стал частью бизнес-процессов: когда мы описываем проект (например, интеграцию с внешними сервисами вроде «Госуслуг»), ссылки на API-методы из схемы добавляются вручную в документы в Confluence. Так мы гарантируем, что в процессах используются реальные и актуальные методы, а не устаревшие версии.

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

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

Swagger без прикрас: где помог, а где усложнил

Swagger кажется очевидным решением, но на практике у него есть и сильные стороны, и ограничения.

Что сработало хорошо

Главный плюс — единый источник данных.

Теперь документация не разбросана по Confluence и разным файлам, а живет там же, где код. Это убирает дублирование и снижает риск неактуальности.

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

Кроме того, Swagger есть почти у всех команд в Рунити, поэтому инструмент не пришлось внедрять заново — только выстроить процесс работы с ним.

Что оказалось сложным

Главный минус — трудоемкость.

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

Еще одна сложность — работа с Git.
YAML-файлы  со схемами Swagger хранятся в репозитории, и для работы с ними нужны базовые навыки командной строки. Для технических писателей это непривычная среда, поэтому поначалу процесс выглядел сложнее, чем был на самом деле.

Наконец, описывать схемы вручную — процесс, требующий внимательности. Любая ошибка в YAML ломает структуру. Проверять себя приходится часто, хотя со временем это становится проще.

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

Рекомендации для тех, кто только начинает

Если вы хотите перейти на документирование API в Swagger, начните с малого.

Мы тоже начали с эксперимента — выбрали одну команду и один проект, чтобы проверить, насколько это вообще выполнимо. Этого достаточно, чтобы понять, подходит ли подход под ваши процессы.

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

2. Не бойтесь консоли.
Git поначалу пугает, особенно если раньше не приходилось с ним работать. Но базовые команды add, commit, push и работа с ветками осваиваются быстро. А когда понимаешь, что документация обновляется вместе с кодом — появляется уверенность, что всё не зря.

3. Используйте шаблоны.
Для первых шагов удобно брать готовые YAML-примеры. Мы ориентировались на открытые шаблоны вроде swagger-openapi-example — они помогают не забыть ключевые разделы и быстрее разобраться со структурой.

4. Не стремитесь к идеалу.
Swagger-файл не обязан быть идеальным с первого дня. Важно, чтобы документация была актуальной и понятной, а формат можно улучшать постепенно.

Главное — понимать, зачем это нужно. Swagger не решит все проблемы с документацией, но помогает убрать дублирование и сделать процесс прозрачнее.

Начали как эксперимент, а продолжаем как стандарт: промежуточные итоги и планы

Для нас эта работа началась как эксперимент, а закончилась пониманием, что подход действительно работает.
Мы убедились: описывать API напрямую в Swagger можно, даже если раньше этим занимались только разработчики.

Теперь у нас есть собственная инструкция, по которой можно подключать новые команды. Сейчас наша цель — чтобы вся документация по API хранилась в одном месте, рядом с кодом, а в Confluence оставались только ссылки.

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

Мы поняли, что можем это делать. Осталось только довести процесс до стандарта.

А как у вас устроена работа с API-документацией? Пишите в комментариях — интересно, кто и как решает проблему актуальности: разработчики, техрайтеры или все вместе.