Комментарии 24
Эрланговый стафф. Историю изменений, в принципе, можно смотреть в нашем форке, он открытый https://github.com/rbkmoney/swagger-codegen/pulls?q=is%3Apr+is%3Aclosed
я помню эти длинные ветки комментариев)
там предложение есть на эту тему кстати https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/003_Clarify-Nullable.md
Все, свершилось, теперь это просто суперсет https://phil.tech/2019/09/07/update-openapi-json-schema/
openapi-codegen работает значительно лучше, по крайне мере для python и typescript. Он поддерживает не все фишки, к сожалению, но клиенты работают довольно неплохо.
PS. пользуясь случаем, привет пятисотому аски-котику, который был не валидным json
Интеграционным тестом. При каждой сборке любого микросервиса для любой ветки в CI разворачивается инстанс процессинга и запускается моча-тест. Он покрывает все 100% методов внешних апи. Для него генерится клиент сваггер-кодгеном из нужной ветки со спекой.
Надеюсь, котики радуют, это было одно из первых моих требований к системе, чтобы в ней можно было получить котика)
Ну а если серьезно, то котик отдается только со статусом HTTP/500, тут уж не до валидации (это для тех кто не еще работал с нами).
Его, кстати, можно принарядить:
{
"error": "oops, 504",
"message":"Мы все починим, а пока держите котика:",
"01":"───────────────────────▄▄",
"02":"──▄──────────────────▄███▌",
"03":"─▐██▄───────────────▄█░░██",
"04":"─▐█░███────────────██░░░██",
"05":"─▐█▌░███──────────██▌░░░▐█",
"06":"──██▌░░██▄███████▄███▌░██",
"07":"──███▌░███░░░░░░░░░░█▌░█▌",
"08":"───██████░░░░░░░░░░░░███",
"09":"───████░░░░░░░░░░░░░░░██",
"10":"───▐██░░░░░▄█░░█▄░░░░░██▌",
"11":"───██▌░▄▓▓▓██░░██▓▓▓▄░██▌",
"12":"───██░▐██████░░██████▌░██",
"13":"──▐██░█▄▐▓▌█▓░░▓█▐▓▌▄█░██",
"14":"──███░▓█▄▄▄█▓░░▓█▄▄▄█▓░██▌",
"15":"──██▌░▀█████▓░░▓████▓▀░░██",
"16":"─▐██░░░▀███▀░░░░▀███▀░░░██",
"17":"─███░░░░░░░░▀▄▄▀░░░░░░░░██",
"18":"─██▌░░░░░░░░░▐▌░░░░░░░░░██▌",
"19":"─██░░░░░░░░▄▀▀▀▀▄░░░░░░░░██",
"20":"▐█▌░░░░░░░▀░░░░░░▀░░░░░░░██▌",
"21":"██░░░░░░░░░░░░░░░░░░░░░░░░██",
"22":"██░░░░░░░░░░░░░░░░░░░░░░░░██",
"23":"██░░░░░░░░░░░░░░░░░░░░░░░░██",
"24":"██░░░░░░░░░░░░░░░░░░░░░░░░██",
"25":"██░░░░░░░░░░░░░░░░░░░░░░░░██",
"26":"██░░░░░░░░░░░░░░░░░░░░░░░░██",
"27":"██░░░░░░░░░░░░░░░░░░░░░░░░██"
}
OpenAPI v3.0 конечно отличается от Swagger v2.0 и в документации примеры не на все случаи жизни, но за два дня можно полностью освоиться.
Но конечно если у вас кодогенератор для версии два, то на версию три этот кодогенератор придётся существенно переписать. И тут то станет понятно насколько ваши абстракции абстрактны, и так ли уж сильно они оторваны от реализации
Платной версии нет, это ж просто спецификация, ее разве что патентом закрыть.
Но тут вопрос в другом — это спецификация в REST иделогии, соответственно как считаете, сессионный токен в кукисах соответствует ей?
Платной версии нет, это ж просто спецификация
Я занимался этим вопросом полгода назад и наверное что то путаю, возможно у них есть опция развернуть Сваггер на каких то их серверах где будет поддержка кукисов, а может быть они в версии 2 не поддерживается вообще ни как, а в версии 3 уже есть варианты (если верить коменту ниже).
В чём была моя задача? Я писал новое API (публичное), но конечно в рамках имеющегося «фреймворка», сиречь кодовой базы, и аутентификация была реализованы через кукисы.
И мне захотелось сделать доку на новое API на Сваггере, за одно у наших клиентов появилась бы возможность интерактивно знакомиться с нашим новым API.
Спеку на API я с горем пополам написал, но дальше аутентификации работать с интерфейсом, который Сваггер нагенерил, было нельзя, потому что кукисы не поддерживались, при этом в IDEA (PhpStorm) я сделал scratch и отлично у меня запросы выполнялись, потому что у IDEA между запросами кукисы сохранятся.
Есть, зато, другая проблема — описание для интерфейса с вебсокетами не поддерживается. И ничего, в общем-то, подходящего тоже нет…
Вроде бы был RAML, но он тоже, кажется, притормозил в развитии (читал что разработчики ушли в OpenAPI)
Использовали 2 года назад js и php клиенты и генерацию документации. Тоже дописывали его. Были проблемы с неймспейсами в php. На фронте токен в хидеры добавляли.
Там уже выше упомянули openapi-generator, но хочу более развернуто описать ситуацию
Жил-был swagger-codegen, поддерживал себе спецификацию swagger 2.0 и не тужил. Потом вдруг откуда ни возьмись появилась OpenAPI Spec 3.0 с новыми вкусными фишками, и разрабы swagger-codegen рьяно принялись пилить его поддержку. Так рьяно, что сильно ушли в сторону от изначального кода, поддерживающего 2.0. На сегодняшний дней поддержка 3.0 все еще ведется в отдельной ветке, и на dockerhub пушатся отдельные образы для v2 и v3. Печаль :(
Но гораздо большая печаль в скорости разработки. Новые релизы выходят редко, баги не правятся годами.
Пару лет назад (может, поменьше) части разработчиков swagger-codegen эта ситуация сильно не понравилась, они сговорились и сделали свой форк — openapi-generator. Этот форк (на настоящий момент уже значительно разошедшийся со своим прародителем) поддерживается гораздо более активно, следует более агрессивному расписанию выката релизов. Единая кодовая база поддерживает и v2, и v3 — один образ, одни и те же люди на поддержке. Комьюнити больше — больше сторонних патчей.
Из минусов — апгрейд минорной версии таки бывает не вполне обратно совместимым.
Swagger в RBK.money — про наши внешние API