Документация действующего API в OpenAPI и Swagger
OpenAPI — это машиночитаемое описание HTTP API, а Swagger UI превращает его в понятную страницу с методами, полями и примерами. Мы восстанавливаем документацию по действующему коду и реальным запросам, сверяем её с тестовым контуром и передаём файл, которому можно доверять при подключении нового партнёра или разработчика.
Когда стоит обратиться
Обычно к нам обращаются в таких ситуациях:
- Партнёры получают адреса методов в переписке, а обязательные поля выясняют во время первых ошибок.
- Рабочее API изменилось после нескольких релизов, и старые примеры уже расходятся с фактическими ответами.
- Команда готовит публичную или внутреннюю интеграцию и хочет согласовать контракт до разработки клиентской части.
- Для API нужны контрактные тесты, генерация клиента или тестовый мок-сервер, а спецификация OpenAPI пока отсутствует.
Что именно мы сделаем
Собираем маршруты, примеры запросов, ответы и правила авторизации.
Выделяем методы, которые участвуют в главных рабочих сценариях.
Описываем параметры, тела запросов, схемы ответов и ошибки в OpenAPI.
Открываем спецификацию в Swagger UI и проверяем контрольные вызовы.
Передаём готовые файлы и порядок обновления документации после релизов.
Что входит в стоимость
29 900 ₽ за всю работу
Изучаем маршруты API, код или рабочие запросы, журналы и существующие описания. Сверяем фактическое поведение приоритетных методов, оформляем схемы запросов и ответов, добавляем авторизацию, ограничения, ошибки и примеры. Проверяем файл валидатором, открываем его в Swagger UI и выполняем контрольные вызовы в доступной тестовой среде.
Что будет готово
Передадим вам
- Спецификация действующего API в формате OpenAPI.
- Swagger UI либо готовая конфигурация для просмотра спецификации.
- Список расхождений между текущим поведением API и исходными описаниями.
- Короткая инструкция по обновлению документации после изменений API.
Перед сдачей проверим
- Файл проходит синтаксическую проверку OpenAPI и открывается в выбранном интерфейсе.
- Приоритетные методы содержат параметры, авторизацию, схемы данных, коды ответов и примеры.
- Контрольные запросы в тестовой среде возвращают ответы, соответствующие спецификации.
- Команда может найти нужный метод и понять состав запроса без обращения к автору API.
Как это выглядит на практике
Документация метода создания заказа
Новый партнёр должен передавать заказы в систему. У него есть рабочий пример JSON, но правила заполнения доставки, скидок и состава покупателя хранятся в переписке с разработчиками.
- 01
Разбираем рабочий запрос и выделяем авторизацию, заголовки, обязательные поля и вложенные объекты.
- 02
Описываем товары, покупателя, доставку, денежные значения и допустимые статусы.
- 03
Добавляем успешный ответ, ошибку валидации и пример повторного запроса с тем же идентификатором.
- 04
Открываем метод в Swagger UI и выполняем контрольный вызов в тестовом контуре.
Что понадобится для работы
От вас
- Доступ к исходному коду, маршрутам либо тестовому контуру действующего API.
- Коллекции Postman, журналы, примеры интеграций и имеющиеся текстовые описания.
- Список приоритетных сценариев и специалист, который подтвердит смысл полей и статусов.
Если у вас немного другая ситуация
Небольшие уточнения, которые помогают довести согласованный результат до рабочего состояния, уже учитываем в цене. Если по ходу работы появится отдельный крупный блок или понадобится платная лицензия, сначала обсудим варианты и стоимость. Расскажите о своей ситуации — подстроим план под неё.
- 3 000 ₽после подписания договора через Диадок
- 26 900 ₽после выполнения, демонстрации и приёмки результата
Предоплата входит в общую стоимость. Оставшуюся сумму оплачиваете после демонстрации и приёмки готовой работы.
Часто спрашивают
Об этой услуге
Можно подготовить OpenAPI без доступа к исходному коду?
Да, если доступны тестовый контур, рабочие запросы и примеры ответов. Код ускоряет разбор редких условий, а основные методы можно достоверно описать по фактическим вызовам и журналам.
Чем OpenAPI отличается от Swagger?
OpenAPI задаёт формат спецификации. Swagger UI читает этот файл и показывает методы, поля и примеры в браузере, а также позволяет выполнять разрешённые тестовые запросы.
Можно описать OAuth, JWT или API-ключ?
Да. В спецификации появится поддерживаемая схема безопасности, необходимые заголовки, области доступа и порядок получения тестовых реквизитов.
Добавляете ли вы примеры ошибок?
Добавляем характерные ответы для авторизации, валидации, отсутствующего объекта, конфликта и внутренних ошибок, которые действительно возвращает выбранный API.
Подойдёт ли эта работа для GraphQL?
Для GraphQL используется собственная схема и отдельные инструменты просмотра. Мы оценим текущий интерфейс и предложим подходящий формат документации для его запросов, типов и ошибок.
Как поддерживать документацию после релиза?
Разместим спецификацию рядом с кодом либо в принятом репозитории и передадим короткий порядок обновления. Следующим шагом можно подключить проверку совместимости в CI.
Рабочие токены попадут в Swagger UI?
В файле остаются только безопасные примеры и описание способа авторизации. Рабочие секреты хранятся в принятом у заказчика защищённом контуре.
Цена и изменения по ходу работы
Цена на странице окончательная?
Да. Перед началом мы сверяем исходные данные и фиксируем результат в договоре. Указанная на странице сумма покрывает согласованную работу целиком, даже если её техническая реализация потребует больше времени, чем ожидалось при оценке.
Что означает резерв незапланированных работ?
Это уже включённый в цену запас времени на небольшие связанные уточнения заказчика, которые появляются после старта: например, добавить поле, изменить формат уведомления или учесть ещё одно условие обработки.
Резерв рассчитывается по формуле: стоимость услуги × 30% ÷ 1 500 ₽. Для услуги за 30 000 ₽ это 6 часов. Эти часы относятся только к дополнительным, заранее незапланированным уточнениям. Они не являются сроком проекта и не ограничивают время на основную работу: согласованный результат мы выполняем полностью.
Можно уточнять детали уже во время работы?
Да. Небольшие связанные изменения обычно помещаются во включённый резерв и не требуют доплаты. Если новая идея заметно меняет результат или превращается в самостоятельную задачу, сначала обсудим подход и стоимость. Любое решение согласуем до выполнения.
Начало работы и оплата
Как оформляются договор и оплата?
Подписываем договор через Диадок. Предоплата составляет 3 000 ₽ и входит в общую стоимость услуги. Остаток оплачивается после демонстрации и приёмки готового результата.
Когда начинается срок выполнения?
Срок отсчитывается после согласования задачи, получения необходимых доступов и материалов, подписания договора и поступления предоплаты. Конкретную дату старта и плановый день готовности подтверждаем перед началом.
Как учитываются платные лицензии и внешние сервисы?
До старта проверяем, нужны ли тарифы, лицензии, сертификаты или дополнительные ресурсы внешних систем. Если они потребуются, заранее покажем варианты и стоимость. По возможности аккаунты и лицензии оформляются сразу на заказчика.
Проверка результата и гарантия
Как принимается готовая работа?
Вместе проверяем согласованные сценарии на контрольных данных или тестовой копии, а затем демонстрируем результат. Для интеграций сверяем передачу данных и обработку ошибок, для сайта — работу нужных страниц и действий пользователя, для отчёта — расчёты и обновление данных.
Какая гарантия действует после сдачи?
На выполненные изменения действует гарантия 3 месяца. Если в изменённой нами части обнаружится ошибка нашей реализации, проверим и исправим её без дополнительной оплаты. Переданные материалы, настройки и код остаются у заказчика.