Комментарии 24
НЛО прилетело и опубликовало эту надпись здесь
НЛО прилетело и опубликовало эту надпись здесь

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

НЛО прилетело и опубликовало эту надпись здесь
Ну сейчас уже использовать swagger смысла особо нет. А у вас в stable именно он.

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

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

Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

Информация

Дата основания
Местоположение
Россия
Сайт
rbk.money
Численность
101–200 человек
Дата регистрации

Блог на Хабре