Pull to refresh

Comments 24

UFO just landed and posted this here
UFO just landed and posted this here

Да, полностью. Пока не припомню чтобы в какие-то ограничения упирались

UFO just landed and posted this here
Ну сейчас уже использовать swagger смысла особо нет. А у вас в stable именно он.

О, а что появилась адекватная альтернатива?

OpenAPI v3.0 он уже не swagger банально даже по формату.

Согласен, стоило сделать об этом ремарку в статье, поправлю.

В OpenApi очень напрягает, что они устроили внутри свой не совсем совместимый форк JSON Schema (например nullable-поля по-разному делаются, и нет части фич типа patternProperties), в итоге смешанные чувства — вроде и стандарт используешь, но и велосипед в наличии.

Наконец-то! Самая крутая новость за месяц!

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":"██░░░░░░░░░░░░░░░░░░░░░░░░██"
}
у Сваггера одна беда — он кукисы не поддерживает (или только за денюжку?), то есть если ваше API пишет токен сессии в куки, то вам такое API с помощью Сваггера не удастся проверить, то есть не получиться на Свеггере сделать интерфейс для работы с вашим API.
OpenAPI v3.0 конечно отличается от Swagger v2.0 и в документации примеры не на все случаи жизни, но за два дня можно полностью освоиться.
Но конечно если у вас кодогенератор для версии два, то на версию три этот кодогенератор придётся существенно переписать. И тут то станет понятно насколько ваши абстракции абстрактны, и так ли уж сильно они оторваны от реализации

Платной версии нет, это ж просто спецификация, ее разве что патентом закрыть.


Но тут вопрос в другом — это спецификация в REST иделогии, соответственно как считаете, сессионный токен в кукисах соответствует ей?

Платной версии нет, это ж просто спецификация

Я занимался этим вопросом полгода назад и наверное что то путаю, возможно у них есть опция развернуть Сваггер на каких то их серверах где будет поддержка кукисов, а может быть они в версии 2 не поддерживается вообще ни как, а в версии 3 уже есть варианты (если верить коменту ниже).
В чём была моя задача? Я писал новое API (публичное), но конечно в рамках имеющегося «фреймворка», сиречь кодовой базы, и аутентификация была реализованы через кукисы.
И мне захотелось сделать доку на новое API на Сваггере, за одно у наших клиентов появилась бы возможность интерактивно знакомиться с нашим новым API.
Спеку на API я с горем пополам написал, но дальше аутентификации работать с интерфейсом, который Сваггер нагенерил, было нельзя, потому что кукисы не поддерживались, при этом в IDEA (PhpStorm) я сделал scratch и отлично у меня запросы выполнялись, потому что у IDEA между запросами кукисы сохранятся.
А, вот тут уточнение — в swagger-интерфейсе (и в OpenAPI) куки так и не поддерживаются. Пишут что это ограничение браузеров (возможно CORS?).
Спека позволяет описать куки-авторизацию и на swaggerhub тоже работают куки.
OpenAPI v3.0 поддерживает кукисы. И если вы начинаете новый проект, то какой смысл брать устаревший Swagger когда есть OpenAPI.

Есть, зато, другая проблема — описание для интерфейса с вебсокетами не поддерживается. И ничего, в общем-то, подходящего тоже нет…
Вроде бы был 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 — один образ, одни и те же люди на поддержке. Комьюнити больше — больше сторонних патчей.
Из минусов — апгрейд минорной версии таки бывает не вполне обратно совместимым.

Sign up to leave a comment.