Comments 11
Проблема обычно начинается с чужими спецификациями, которые написаны криво.
Самый банальный пример - инлайн объектов. В итоге генерируется код с кучей Inline406ResponseObject и т.д.
Как вы решали эту проблему? Ведь чужую спецификацию не исправить.
Страдаем от того как написаны некоторые наши кор системы (
И экспериментируем с их апи чтобы хоть что-то рабочее сгенерировалось. В контексте нашего продукта - все полтора десятка интеграций спрятаны за сервисами-адаптерами или гейтвеями. И вот апи этих адаптеров мы пишем сами, а там даже если когда-нибудь не сможем написать спецификацию другой системы - ну, будет написано руками. Но хоть в одном месте
У нас так же интеграции спрятаны за сервисами-адаптерами. Так как интеграций несколько десятков и все они разные.
Внутри своего продукта не проблема писать нормальные апи (единственная проблема - легаси сервисы, которых порядком).
В итоге генерировать контракт и dto получается только для новый микросервисов.
Для имеющихся пишем руками.
Всегда работал исходя из подхода "Сначала интерфейс, потом контракт, потом клиент". Ну ладно, лукавлю, не всегда. Но как только попробовал - отказаться уже не смог. Под интерфейсом я подразумеваю моки эндпойнтов на сервере, облепленные докстрингами настолько, насколько это вообще возможно. Из получившихся моков как правило без особых проблем собирается опенапи спецификация, из которой также без проблем генерируется пакет для клиента (генератор тут незаменим). Когда цепочка налажена, весь алгоритм можно запихнуть в какой-нибудь Gitlab CI/CD, и вот уже после обновления сервера мы можем автоматом получать необходимые клиенту пакеты, которые аккуратно складываются в корпоративный реестр.
Алгоритм автора мне кажется наиболее подходящим при работе в большой команде, когда разработчик сервиса и разработчик клиента могут быть даже не особо знакомы, не говоря уже о тесном сотрудничестве. Кстати, а можете ли посоветовать какие-то инструменты для удобной разработки опенапи спецификации? Я могу её, конечно, руками писать, но удовольствие это то ещё, если честно. Знаком разве что с Апикуром, но он не то чтобы про удобство...
Пробовали как раз Апикур да swagger-editor. Но к сожалению из-за разных сред работы (разработчики и тестировщики, инхаус и аутстафф, корпоративная техника и терминалу), из общего у нас осталась только IDEA, в которой из коробки идёт OpenAPI плагин, здорово помогающий с рендерингом спецификации. То есть даже не нужно ничего запускать, просто открываешь в Идее файл и он тут же отрисован в swagger ui. А пишем руками...
Минусы всяческой генерации в том, что разработчики, вместо того, чтобы прописывать все в коде, прописывают все в каких-то левых сущностях. То-же самое количество объектов - полей, интерфейсов, но только не в коде, где они уже привыкли, где все удобно, все быстро работает, все на глазах и под руками - а в каких-то левых файлах, в xml, json, в @ и так далее, в худшем случае - в самописном web-приложении ("для удобства") в табличках. Все это работает криво-косо, никаких диагностических сообщений (у вас же наверное принято глотать эксепшены, коих как огня боятся?).
Ответьте на простой вопрос - где удобнее делать опечатки - в своем коде или в стороннем репозитории? В чем ускорение процесса? В том, что добавляется генерация, появляется необходимость сшивания сгенированного кода и кода логики? Всякое там наследование и шаблоны применять...
Генерация контрактов OpenApi или прикладной API first: совсем немного про зачем