Comments 9
Какой оригинальный подход - измерять перспективность новой версии формата через количество строк и уровней вложенности.
Вот чего OpenAPI не хватает, так это строгости, чтобы запретить некорректные интерфейсы. А для этого стоит попробовать уйти от абстрактных JSON схем на каждом углу, и уделить больше времени дизайну собственно архитектуры API и ключевых деталей.
Генераторы тоже головную боль создают. 3.1 не всеми поддерживается вообще. 3.0 поддерживается как попало, и не весь функционал спецификации приводит к корректно сгенерированном коду.
Для серверной части пока только Connexion достоин внимания. Клиентская часть - autorest.
А стандартный генератор производит лишний мусор, который ни интегрировать, ни изолировать в проекте нельзя.
Какой оригинальный подход - измерять перспективность новой версии формата через количество строк и уровней вложенности.
Если рассматривать подход "API first", то вполне значимый критерий.
О да... На этом мы собственно и застопорились при внедрении API First. Если нельзя использовать генератор без напильника, то смысл автогенерации теряется совсем. Видимо придётся писать свои генераторы под свои потребности, потому что то, что позиционируется как официальные инструменты, не работает как надо. К этому добавляется не очень хорошая поддержка многофайловых схем в инструментах, а в одном файле все держать очень не очень
Для серверной части пока только Connexion достоин внимания
Мы довольно успешно используем apispec для подхода api-first: пишем классы на питоне, потом генерируем по ним спеку. OAS 3.1 неплохо поддерживается
Клиентская часть - autorest.
Можете сравнить с другими генераторами? Чем он вас больше приглянулся, в каких случаях работает лучше других? Мы используем openapi-generator (генератор typescript-angular) с кастомными шаблонами. Поддержка 3.1 пока экспериментальная, но у нас завелось.
А стандартный генератор производит лишний мусор
А какой именно генератор для вас стандартный?
Мой случай следующий:
Небольшой веб-сервис c OpenAPI UI, предоставляет просто API, и взаимодействует с несколькими другими API. OpenAPI 3.0 нам было достаточно. Внешние сервисы: Swagger 2 или OpenAPI 3.0 тоже. API Клиент не предполагает распространение, и скорее для внутренних нужд и тестирования сервиса, однако для внешних сервисов хозяева сервисов клиенты не предоставляют.
Главные требования к выбору генератора - API Spec First, чтобы фокусироваться на контракте, а не на коде; изоляция сгенерированного кода от реализации в целях проверки совместимости типов и декларации интерфейса; минимальное количество ручной работы по выполнению тривиальный операций преобразования форматов; Язык - Python, Сервер приложений не важен, лишь бы было четкое разделение, где свой код, где генерированный.
Стандартным генератором я бы назвал https://github.com/swagger-api/swagger-codegen. Выглядит достаточно официальным, предлагает генераторы для сервера и клиента. Вот к нему основная претензия в неочевидном мусоре. Генерируется куча всего, развалено как попало, да еще и как jar файл распространяется. Без экосистемы разработки на Java было крайне нетривиально его запустить в CI/CD, а интегрировать в Python package структуру проекта оказалось неподъемно. Какое-то оно оказалось, Java-style что ли...
После активного поиска и в целом разочарования по серверным генераторам, пришли к https://github.com/spec-first/connexion, с ним необычно, что генерации серверного кода нет вообще, и фреймворк реализует весь бойлерплейт на лету в рантайме, но вменяемая и тривиальная интеграция через operationID атрибут нас устроила. Имеем API Spec файл, который при сборке подсовывается в connexion и это все запускает с guvicorn. Если какие-то контракты не соблюдены - на старте ругается на несоответствие схемы и реализации.
С генерацией клиента оказалось проще, но интереснее Альтернатив полно.
Разные команды у нас используют OpenAPI чуть-чуть по-своему, и неограниченные генераторами иногда публикуют некорректные спецификации. Как первый попавшийся генератор, который минималистичный и изолированный: https://github.com/openapi-generators/openapi-python-client. Буквально 3 файла для импорта в собственно приложение и всё. 3 из 5 клиентов до сих пор генерируем этим генератором.
А вот для двух других сервисов, openapi-python-client создает некорректный код клиента или просто валится с ошибкой парсинга, и никаких шансов изменить спецификацию. Так пришли к https://github.com/Azure/autorest, который смог успешно прожевать, хотя и ругаясь предупреждениями. Пришлось отключить строгую проверку типов, но в целом нас устроило. Целиком не мигрировали на autorest из-за лени и нежелания трогать то, что работает.
А OpenAPI может содержать описание WebSocket запросов?
Сначала ругают wsdl за то что он сложный и непонятный, а потом делают то же, но долго и на json
OpenAPI станет проще: готовится версия 4.0