OpenAPI Generator: клиент API площадки без ручного кода

Откуда берутся ошибки в ручном клиенте

Разработчик читает документацию площадки и переносит её в код руками. В методе сорок полей, в трёх из них число, а он записал строку. Площадка добавила обязательное поле, клиент про него не знает, и выгрузка остатков тихо перестаёт идти. Программисты тут ни при чём. В спецификации Ozon Seller API, которую я загрузил 15.10.2026, 483 метода и 2305 описанных структур данных. Держать такое в голове невозможно.

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

Что такое OpenAPI Generator и жив ли проект

Генератор берёт спецификацию OpenAPI версий 2.0 и 3.0 (поддержка 3.1 в README помечена как beta) и выдаёт код. Лицензия Apache-2.0, я проверил по файлу LICENSE в репозитории. Проект создан 12 мая 2018 года, у него около 26 800 звёзд и 405 авторов кода.

Последний релиз 7.26.0 вышел 6 октября 2026. До него были 7.25.0 в конце августа и 7.24.0 в июле, то есть версия выходит раз в месяц-полтора. С 15 сентября в репозиторий попало около 195 коммитов, а в первой сотне из них отметились 39 разных авторов. Открытых issue 5138 и ещё 615 pull request. На быстрое исправление чужого бага рассчитывать не стоит, проще поправить шаблон у себя.

Как запускается и сколько там языков

Это утилита командной строки. По README её ставят через npm-обёртку @openapitools/openapi-generator-cli (нужна Java), скачивают jar с Maven Central (минимум Java 11), берут Docker-образ или Homebrew. Есть плагины для Maven и Gradle. Команда одна: файл спецификации, язык и папка для результата.

По странице генераторов в документации я насчитал 171: 80 клиентских, 73 серверных, 9 для документации, 8 для схем (SQL, GraphQL, protobuf и другие) и один конфиг Apache. Для типичной интеграции нужны python, php, java, csharp, go, kotlin, ruby и typescript-fetch, и у каждого в документации стоит статус STABLE. Но у универсального typescript статус EXPERIMENTAL, а у php-nextgen BETA. Среди клиентских генераторов 16 помечены beta, 4 experimental и 2 deprecated, поэтому статус своего языка смотрят до начала работы.

Публичный онлайн-сервис api.openapi-generator.tech 15.10.2026 отвечал, но README называет такие сервисы beta без гарантий. Спецификацию с вашими внутренними методами туда отправлять не стоит. Для этого есть образ openapi-generator-online, он поднимается у вас на сервере.

Есть ли спецификации у площадок

Яндекс Маркет: в документации есть отдельная страница про OpenAPI, спецификация лежит в репозитории на GitHub (последнее обновление 15.10.2026). Там прямо написано, как сгенерировать клиент этим самым генератором, с командой для npx.

Ozon: на странице документации ссылки на файл я не нашёл. Но по адресу docs.ozon.ru/api/seller/swagger.json отдаётся OpenAPI 3.0.0 размером около 3,7 МБ, версия документа 2.1. Адрес я нашёл подбором, поэтому он может поменяться.

Wildberries: в английской версии раздела API написано, что документация дана в формате Swagger OpenAPI и подходит для импорта в Postman и генерации клиентского кода. Прямую ссылку на файл спецификации я не нашёл, так что скачивается ли он одним кликом, не подтверждено.

Шаблоны Mustache

Внутри генератора лежат шаблоны Mustache. Свои подкладывают параметром -t (в Maven это templateDirectory, в Gradle templateDir). По документации в девяти случаях из десяти хватает правки этих файлов. Так в каждый клиент вшивают свой логгер, заголовки авторизации и повтор запроса после ошибки 429, которую площадки возвращают при превышении лимитов. Ограничение: шаблоны можно только переопределять, новых файлов через них не создать.

Что важно учесть

Генератор даёт методы вызова и модели данных. Как сопоставить артикулы с 1С, когда слать остатки и как уложиться в лимиты, пишется отдельно, этого в нём нет.

Спецификация определяет всё. Если в ней нет поля, которое площадка отдаёт на деле, в клиенте его тоже не будет. В файле Ozon адрес сервера записан без протокола (//api-seller.ozon.ru), как с этим справится генератор, я не проверял.

Версию генератора фиксируют. В таблице релизов README у 7.26.0 и у будущей 7.27.0 стоит пометка о breaking changes (с запасным вариантом). Сгенерированный код кладут в git, а при смене спецификации смотрят diff. И README предупреждает: спецификацию из недоверенного источника просмотрите до генерации, иначе возможна инъекция кода.

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

Что можно сделать уже сейчас

Первое. Возьмите спецификацию своей площадки и сгенерируйте клиент на вашем языке в отдельную папку. Для начала хватит одной команды из документации Маркета.

Второе. Сравните результат с тем, что написано руками. Пропущенные поля и неверные типы обычно находятся за вечер.

Третье. Зафиксируйте версию: в npm-обёртке это команда openapi-generator-cli version-manager set 7.26.0. Запросы к тестовому контуру удобно проверять в бесплатном клиенте для HTTP.

Четвёртое. Если интеграций несколько, подключите перегенерацию в CI. Когда площадка обновит файл, сборка покажет, что изменилось в клиенте. Если вы только знакомитесь с темой, начните со статьи что такое API простыми словами.

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

Нужно ли знать Java?

Писать на Java не нужно, но для запуска нужна JVM: и у npm-обёртки, и у jar-файла. Если Java поставить нельзя, в README для этого случая предложен Docker-образ.

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

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

Сколько стоит внедрение?

Цену без вашей спецификации я не назову: многое зависит от числа методов и языка. Ориентиры есть на странице цен и в статье про стоимость интеграции API.

Коротко о главном

OpenAPI Generator бесплатный и живой: релиз 6 октября, десятки авторов в месяц. У Маркета и Ozon спецификации можно взять сегодня, у Wildberries API описан в Swagger OpenAPI. Клиент на нужном языке собирается за минуты, а человеку остаются логика обмена, тесты и контроль версий. Как мы подключаем это к проектам заказчиков, описано на странице интеграции систем.

Интеграции с маркетплейсами, банками или 1С пишутся вручную и ломаются от каждого обновления API? Напишите мне в Telegram кодовое слово «СПЕКА». Посмотрю спецификацию ваших площадок и скажу, какие клиенты можно сгенерировать, а что придётся дописывать руками.