Огромное человеческое спасибо! Самый лучший и, к сожалению, единственный на всем тюбике понятный урок как писать схему OpenAPI. Автор, дай бог тебе здоровья!
Огромное спасибо за видео! Прохожу обучение в нетологии на курсе "системный аналитик", так вот ваше видео помогло разобраться в swagger, в отличие от учебного видеоурока!
Антон, спасибо Вам огромное за это видео!!! Максимально понятно, легко на слух и подробно! Поняла всё с первого раза :) Разошлю всем коллегам! Спасибо за то, что облегчили жизнь сразу нескольких джунов СА :)))
На самом деле зависит от того, где вы будете создавать спецификацию. У большинства программ есть синхронизация с гитом, например, та же insomnia. Ещё есть apicurio. Там уже и делиться особо не надо. Сразу у всех единый доступ к созданию и описанию api.
Ахахаха, спасибо))) На Винде зажать кнопку win и стрелочки вправо влево. Текущее открытое приложение займет пол экрана. А дальше можно курсоров додвинуть, если надо не половину, а как-то иначе.
👍💪Интересно было бы посмотреть, как описываются пути с 2мя вложениями. Например libraries/{libraryid}/halls/{hallid} И ещё не затруднит тебя объяснить что такое security ?
На самом деле отличий то особо и нет. Единственный вопрос, на который стоит ответить самому себе, а нужно ли так делать, может, просто /halls/{hallid} ?)) Но если делать, то получится что-то похожее на: /libraries/{libraryid}/halls/{hallid}: get: summary: Метод получения сущности по идентификатору operationId: getHallById parameters: - name: libraryid in: path required: true example: 22bbbb2b-8b9c-4af9-88f7-0bc180cf74b4 schema: type: string - name: hallid in: path required: true example: 11aaaa2b-8b9c-4af9-88f7-0bc180cf74b4 schema: type: string Про security, если дойдут руки, тоже попробую сделать видео. Если вкратце, это описание способов аутентификации (basic, oauth, openid), заполнив которые, мы затем помечаем методы соответствующими правами (permission/scope). Когда клиент отправит запрос, у него будет проверяться наличие указанных на методе прав
Спасибо! А теперь как из этого сгенерить классы java c компонентом Spring'а @Controller и классы простых объектов Toy, Toys, Error ? Думаю, что я сейчас нарою ответ, но предчувствую, что это будет в новом видео :)
Спасибо за видео! Я студент, учусь на программиста, делаю веб приложение и фронту в моей команде очень нужна дока по api, который я написал, в видео вы обьясняете все четко, но есть пара вопросов: 1) Я правильно понимаю, что единственный способ поделиться с ним документацией - скинуть ему этот yaml файл? Я себе по другому представлял немного, что создается личная дока на которую можно скинуть ссылку, чтобы человек посмотрел 2) Смогу ли я сделать документацию без регистрации на платформе? Возможно, для мини проекта можно было оставить документацию в каком нибудь гугл доке или вобще в блокноте, но хочется сделать красиво)
Успехов вам в обучении! По вопросам выходит так. 1. Скинуть yaml файл - на первых порах действительно самый простой вариант. Когда у вас появится развернутое приложение на сервере/облаке, то можно добавить зависимость swagger-ui и тогда приложение поднимет ui со спекой (можно читать, отправлять запросы, скачать спеку). Мы у себя в проекте запили 1 маленький микросервис, который поднимается вместе со всеми спецификациями наших микросервисов. И из одной точки удобно смотреть все спеки и оправлять любой запрос в любой микросервис. 2. Регистрация не нужна, там хоть в блокноте можно создавать. Поддержку рендера openapi спек имеет множество инструментов. Например, insomnia (аналог постмана), jetbrains продукты, vs code.
Не подскажите, есть ли где то руководство на русском, что бы понятно было описано какой параметр для чего нужен? Находила пару ресурсов, но там такой костыльный перевод.
Привет! Я их, честно говоря, не использовал, так что сходу, к сожалению, не смогу подсказать ничем кроме документации. Как обычно там на примере всё легко, но нужно попробовать руками, а потом уже советовать)) Спасибо за идею, возьму на заметку!
Отличный вопрос, я его ждал:) Я знаю 2 варианта. 1ый - используется при автогенерации кода по спецификации для наименования методов. Если operationId = getToyById, то в коде соответствующий метод будет похож на ResponseEntity getToyById(...) {...}. Если интересны детали, то предлагаю посмотреть мое видео про генерацию: ua-cam.com/video/HAGSYTN7lZQ/v-deo.html 2ой - используется для якорей в документации, так как значение operationId должно быть уникальным среди всех методов.
Точно вопрос про версию OAuth 3? Последняя на данный момент 2.1. А если все-таки цель подружить OpenAPI 3 с OAuth 2, то я советую вам посмотреть на их документацию в первую очередь. Там с примерами. swagger.io/docs/specification/authentication/oauth2/
Да, может. Но если идентификатор генерируется на строне сервера, то лучше делать просто POST /toys. А так можно делать хоть get /toys/{id}, который будет удалять эту игрушку:) Ограничений, кроме адекватности нет.
Как сделать так что бы в Схеме можно было указывать несколько игрушек? Практиковался на вашем примере но постоянно выдавало ошибку "duplicated mapping key"
@@IT_like_bricks_building В целом да, чтобы несколько игрушек отображались в методе (в интерфейсе справа). Допустим я хочу добавить ещё одну игрушку, и чтобы она тоже отображалась в результате успешного запроса. Ну там "Train" и например "Car". При попытке сделать новый объект в "компонентах" у меня либо появлялась эта ошибка о дублировании, либо о том что "объект" ещё не дописан. В любом случае, справа в результате запроса, появлялась только одна из двух созданных мной игрушек. Как сделать так чтобы можно было показать весь перечень объектов (игрушек), которые записаны в компонентах? У меня получилось так сделать только если описывал их прямо в "path", но тогда создавать ссылки нельзя. Буду признателен за помощь.
Кажется, я понял, о чем был вопрос. В разделе "paths" есть возможность использовать "examples", посмотрите на возвращаемое значение у метода get /toys в случае успеха. Там поезд и самолет возвращаются. Но это пример под конкретный метод, что не есть универсально. А вот в разделе "components" нет возможности использовать "examples", только "example". Покрутил, попробовал, ничего дельного не смогу посоветовать, не придумал.
Автоматизацию через insomnia мы не делали. Мы сразу пошли по пути использования спец приложений, например, dredd (есть видео на канале) и microcks (более современен)
@@IT_like_bricks_building т.е по вашему опыту (опыт вашей команды), на текущий момент автоматизацию тестирования API лучше всего реализовывать через dredd и microcks, чем на том же постман / инсомния или на Java с использованием Rest assured?
Мне кажется, что если мы говорим про автоматизацию, то нам всем хотелось бы, чтобы сами тесты +/- автоматически генерировались по имеющейся OpenApi спецификации. Поэтому я бы выбирал те инструменты, которое это умеют из коробки делать. Postman вроде бы умеет работать со спецификацией (генерировать коллекцию запросов по ней), у нас в одном из проектов как раз на нем тесты и сделаны. Но там руками много всего вносится нового, поэтому я бы не назвал это автоматизацией, хотя может мы не докрутили где-то. Insomnia для авто тестов мне не особо понравилась, хотя она тоже генерирует коллекцию запросов по спецификации. Dredd и Microcks прям специализируются на решении обсуждаемой нами задачи, только dredd не полностью поддерживает 3ю версию OpenApi. Rest Assured, как я вижу, тоже не особо дружит с автогенерацией тестов, хотя, может, доп плагинами проблема и решается. В общем если начинать новый проект, я бы использовал Microcks. А ещё лучше сразу Apicurio для проектирования спецификаций, внутри которого уже встроен Microcks для тестов:)
Добрый день, подскажите пожалуйста, как описывать обязательные header - ы. Необходимо в некоторых (не всех) запросах вставлять хидером сессионный ключ авторизации. Что-то читаю документацию, гуглю, вставляю все в редактор сваггера и ничего не получается. Пытаюсь составить доку в версии 3.0.3, пример находил в версии 1.0.0. Не заработало, может быть из-за версии. Три часа провозился и никакого результата. Сейчас остановился на следующем: paths: /toys: post: requestBody: ... responses: ... parameters: - session_key: $ref: "#/components/headers/session_key_header" components: schemas: ... headers: session_key_header: description: ... schema: type: string
Добрый день. Вроде бы рекомендуется использовать components/parameters для этого. Посмотрите на эту страницу, мне кажется, это то, что вы ищете github.com/swagger-api/swagger-editor/issues/1827
@@IT_like_bricks_building Подскажите как подтянуть? как сделать так, что документация была в моем проекте по определенному урлу, приложение написано раньше чем дока, вот теперь сформированную доку в editore нужно как-то разместить в проекте, по определенной ссылке, подскажите как??? пожалуйста!
Немного поздно заметил вопрос, думаю, вы уже справились. Но ответ таков, что подключаем в проект зависимость swagger ui, и там указываем путь к спецификации. По итогу при старте модуля на url:port/swagger-ui/index.html (вроде бы так) откроется ваша спецификация
Огромное вам спасибо, я нашел много роликов, но только вы так четко, кратко и точно описали все методы, получилось с первого раза. Подскажите пожалуйста, а можно ли через такую спецификацию описывать зависимости между @Entiey для Hibernate ?
Рад, что видео было полезным для вас! А ответ на ваш вопрос, честно говоря, не знаю, не пробовал. Если вы уже выяснили, напишите, пожалуйста. Вдруг кому-то пригодится.
Все верно. Если идти по пути сначала код, а потом авто генерация спецификации, то да, ваш вариант как раз то, что нужно. А вот если наоборот, то придется ручками написать) Хотя и тут есть упрощения. Можно использовать конструкторы спецификации, например, Apicurio (когда-нибудь сделаю видео по нему).
@@IT_like_bricks_building а в чем разница между автоматической и ручной спецификации? Написал апи, хочу спецификацию сделать к нему, вот думаю, сделать через генерацию или самому прописать все.
Разница именно в подходе. В некоторых проектах команда идёт по пути, когда сначала аналитик проектирует и создаёт спецификацию, а затем разработчик разрабатывает по ней или автоматом генерирует код по спецификации. В некоторых компаниях делают наоборот. Пишут код, помечают методы аннотациями и тд, бонусом получают спецификацию при сборке.
Спасибо вам большое, вся информация изложена очень обстоятельно и доступным языком. Будьте добры, подскажите как я могу проверить написанную спецификацию, например создать игрушку, потом запросить список игрушек или описание игрушки по ее id? При этом цель просто проверить, что все ошибки, атрибуты и т.д. в спецификации указаны правильно. То есть если я правильно понимаю, нужен локальный сервис созданный по спецификации (причем не важно на каком языке, я не разработчик, я просто проектирую спецификацию). В идеале в Docker. Насколько я понимаю такой класс продуктов называется Mock сервера, но я не смог найти ни один который бы понял спецификацию Swagger Petstore - OpenAPI 3.0 (демо спецификация) - просто на ней тестировал исходя из того что уж она точно написана по стандарту. Данное видео (ua-cam.com/video/HAGSYTN7lZQ/v-deo.html) но там к сожалению уже сложно и описывается как модифицировать код серверной части. К сожалению уже сложно да и как автор говорит даже те правки по небольшой схеме это только самое начало тех ошибок с которыми придется столкнуться. Кажется получается слишком трудоемко чтобы просто проверить что в спецификации нет ошибок.
Огромное спасибо за фидбек! Могу посоветовать для ваших нужд Prism ( stoplight.io/open-source/prism ), лично я не использовал, но слышал очень хорошие отзывы. Еще рекомендую отличный сайт openapi.tools/ , там есть много всего полезного для OpenAPI. В частности раздел "Mock Servers", там и Prism, и много других. Я как-то использовал в одном из видео Mocklab для тестов спецификации, в целом было нормально.
Я ниже в комментариях уже отвечал на аналогичный вопрос, значение атрибута будет использовано при генерации кода по спецификации. Оно станет названием соответствующего метода в коде.
а для чего нужен этот конструктор? Просто поиграться? Не нашел никакой информации в инете как его можно привязать к Api, что б вместо автоматически сгенерированной документации, отобаражалсь она
Я не понял вопроса скорее всего. OpenApi - это описание api сервиса, один из вариантов его четкого однозначного описания машинным языком и одновременно человеческим. По генерации есть два варианта. По коду сервиса строить спецификацию или наоборот по спецификации код генерировать.
Спасибо) на самом деле я думал об этом, когда монтировал видео. Но подумал, что это лучше, чем много воды и долго. Коротко и по делу)) Попробуйте принять основную мысль, которую я пытался вложить в видео. Документация не так страшна, как может показаться в первый раз. И делайте паузы. Успехов вам в обучении!
Да нихрена не информативно. С первых же секунд не понятно, где автор нашёл документацию ??? - на главной странице нет никакой ссылки ! Хорошо что Гугл знает, где она находится. Второй вопрос - Где автор нашёл эдитор ? Не плохо бы объяснить, т.к. с главной страницы мы попадаем на репозиторий ГитХаб и что с ним делать, нигде не написано - говорят лишь, есть такие во скрипты, а как это приложение запускать ?! Это позор для тех, кто создал такое приложение и так представляет информацию пользователям. И странно что автор видео совершенно не замечает этих проблем.
Ссылки достаточно для разработчиков. Там исчерпывающая инфа для создания Api. Останется только бизнес логику описать, то есть какие действия модуль делает при получении определенного запроса
Огромное человеческое спасибо! Самый лучший и, к сожалению, единственный на всем тюбике понятный урок как писать схему OpenAPI. Автор, дай бог тебе здоровья!
Спасибо вам большое за такой фидбек! Очень радостно, когда есть реальная польза от трудов.
@@IT_like_bricks_buildingприсоединюсь. Самое годное, что я нашёл по Swagger. Отсутствие новых видео 8 месяцев огорчает. :(
@@tusman4ik спасибо! Про новые видео полностью согласен с вами. Но мне нужно время на это, которого не хватает.
Супер, спасибо, как раз то, что я и искала: максимум практики!
Отлично, успехов вам!
Счастья, здоровья, детей красивых. Ментальное здоровье сохранено благодаря этому видео! 😅
Благодарю!))
Без этого видео я скорее всего пошел на зарубежный ютуб, ибо на РФ ничего норм найти не смог. Видео очень пригодилось. Большое тебе спасибо!
Спасибо за такие слова!
Шикарный урок, единственный полезный среди кучи мусора и воды. Спасибо!
Спасибо, я старался 😉
Согласен! Бриллиант среди мусора!
Благодарю!
Впервые пишу комент на тьюбе) просто хочется человеку сказать СПАСИБО!
Очень просто и доходчиво, прекрасны и подача, и сам материал. Большое спасибо!
И вам спасибо за слова!
Огромное спасибо за видео! Прохожу обучение в нетологии на курсе "системный аналитик", так вот ваше видео помогло разобраться в swagger, в отличие от учебного видеоурока!
Спасибо, очень приятно! Успехов вам
Антон, спасибо большое за это видео и за подробное объяснение ваших действий
Как аналитик, раз в пол года приходится с апишками работать и очень удобно по твоему видео вспоминать) ну и chatgpt конечнО)
Классно!)) Признаюсь, я и сам иногда пересматриваю😉
Антон, благодарю, достаточно доходчиво объяснили как с нуля написать спецификацию, полезно
Спасибо!)
Мне кажется просто невозможно понятнее объяснить, спасибо!
Спасибо, старался))
Спасибо. Наконец что-то понятное.
Антон, спасибо Вам огромное за это видео!!! Максимально понятно, легко на слух и подробно! Поняла всё с первого раза :) Разошлю всем коллегам! Спасибо за то, что облегчили жизнь сразу нескольких джунов СА :)))
Супер!! Благодарю за столь приятный отзыв!
очень информативный, краткий и понятный урок, спасибо вам
Благодарю вас за теплые слова!
Весело и просто!
Спасибо!
Рад стараться!
Максимально информативный урок! Спасибо!
Благодарю!
Спасибо, ты молодец
Спасибо!
Очень крутой урок! Можно вам попросить сделать больше видео про сваггер, про АПИ. Как описывать апи, ручки и тд! Надеюсь, буду услышана) спасибо
Спасибо. У меня в планах есть как минимум одно видео про то, каких правил в целом нужно придерживаться при проектирование api. Надеюсь, будет полезно.
@@IT_like_bricks_building дааа, очень жду! я развиваюсь в системной аналитике и это прям очень нужно!
Спасибо большое за этот пример! очень помогло!
Супер) Я очень рад!
Спасибо!! Топ!!
Спасибо за видео! Сразу становится понятней)
Отлично!
Спасибо за видео. Коммент в поддержку!
Спасибо Вам большое 🤍
Спасибо!
Спасибо большое! Быстро и понятно. Не понятно только, где документация хранится и как ей поделиться
На самом деле зависит от того, где вы будете создавать спецификацию. У большинства программ есть синхронизация с гитом, например, та же insomnia.
Ещё есть apicurio. Там уже и делиться особо не надо. Сразу у всех единый доступ к созданию и описанию api.
ОГРОМНОЕ СПАСИБО!!!!!!
Пожалуйста!
@@IT_like_bricks_building единственный ролик, который на практике показал как с этой штуковиной справиться! Еще раз спасибо!
Успехов вам!
Вот уж действительно it как конструктор лего
Спасибо за видео!
Круто, что было полезно)
Спасибо огромное! Единственное полезное видео, в котором все понятно
Успехов в изучении!
Самое крутое видео, из множества, которые смотрел по этой теме! Спасибо за труд!!!
Благодарю за обратную связь!
Пушка! 👍
Большое спасибо за ролик
Пожалуйста!
Супер!!!
Спасибо!
Видео супер! Но вопрос не совсем по теме. Как так окна разделить удобно??
Ахахаха, спасибо))) На Винде зажать кнопку win и стрелочки вправо влево. Текущее открытое приложение займет пол экрана. А дальше можно курсоров додвинуть, если надо не половину, а как-то иначе.
Я как-то пропустил момент касающийся Схем. (schema) что ? откуда куда?))
👍💪Интересно было бы посмотреть, как описываются пути с 2мя вложениями. Например libraries/{libraryid}/halls/{hallid}
И ещё не затруднит тебя объяснить что такое security ?
На самом деле отличий то особо и нет. Единственный вопрос, на который стоит ответить самому себе, а нужно ли так делать, может, просто /halls/{hallid} ?))
Но если делать, то получится что-то похожее на:
/libraries/{libraryid}/halls/{hallid}:
get:
summary: Метод получения сущности по идентификатору
operationId: getHallById
parameters:
- name: libraryid
in: path
required: true
example: 22bbbb2b-8b9c-4af9-88f7-0bc180cf74b4
schema:
type: string
- name: hallid
in: path
required: true
example: 11aaaa2b-8b9c-4af9-88f7-0bc180cf74b4
schema:
type: string
Про security, если дойдут руки, тоже попробую сделать видео. Если вкратце, это описание способов аутентификации (basic, oauth, openid), заполнив которые, мы затем помечаем методы соответствующими правами (permission/scope). Когда клиент отправит запрос, у него будет проверяться наличие указанных на методе прав
Подскажите пожалуйста, в каком в виде хранятся документы в swagger?
Спасибо за урок! Но вот вопрос: А куда потом этот файлик совать в проекте? Сделали спецификацию, а дальше что?
Дальше есть варианты. Можно сгенерировать код, можно использовать как документацию и передавать другим сервисам
Спасибо! А теперь как из этого сгенерить классы java c компонентом Spring'а @Controller и классы простых объектов Toy, Toys, Error ?
Думаю, что я сейчас нарою ответ, но предчувствую, что это будет в новом видео :)
Swagger codegen или аналоги. Мне нравится сайт openapi.tools/ Можно там найти почти всё.
А так да, вы правы. Нужно запилить ещё видео))
Подскажи, а как добавляется сущность чтобы указывать производителя игрушки?
дай Бог тебе здоровья и девушку с 4 размером груди автор! Спасибо!😄
Благодарю))))
Спасибо за видео! Я студент, учусь на программиста, делаю веб приложение и фронту в моей команде очень нужна дока по api, который я написал, в видео вы обьясняете все четко, но есть пара вопросов:
1) Я правильно понимаю, что единственный способ поделиться с ним документацией - скинуть ему этот yaml файл? Я себе по другому представлял немного, что создается личная дока на которую можно скинуть ссылку, чтобы человек посмотрел
2) Смогу ли я сделать документацию без регистрации на платформе?
Возможно, для мини проекта можно было оставить документацию в каком нибудь гугл доке или вобще в блокноте, но хочется сделать красиво)
Успехов вам в обучении!
По вопросам выходит так.
1. Скинуть yaml файл - на первых порах действительно самый простой вариант. Когда у вас появится развернутое приложение на сервере/облаке, то можно добавить зависимость swagger-ui и тогда приложение поднимет ui со спекой (можно читать, отправлять запросы, скачать спеку).
Мы у себя в проекте запили 1 маленький микросервис, который поднимается вместе со всеми спецификациями наших микросервисов. И из одной точки удобно смотреть все спеки и оправлять любой запрос в любой микросервис.
2. Регистрация не нужна, там хоть в блокноте можно создавать. Поддержку рендера openapi спек имеет множество инструментов. Например, insomnia (аналог постмана), jetbrains продукты, vs code.
@@IT_like_bricks_building благодарю за ответ! подписался)
Подскажите, в url сервера что писать? Постоянно выдаёт ошибку
Не подскажите, есть ли где то руководство на русском, что бы понятно было описано какой параметр для чего нужен? Находила пару ресурсов, но там такой костыльный перевод.
К сожалению, мне не попадался, но я и не искал.
Привет! Нет ли у тебя инфы по использованию links? В проекте есть токены, не пойму, как настроить links для их использования.
Привет! Я их, честно говоря, не использовал, так что сходу, к сожалению, не смогу подсказать ничем кроме документации. Как обычно там на примере всё легко, но нужно попробовать руками, а потом уже советовать))
Спасибо за идею, возьму на заметку!
Помогите пожалуйста написать апи для интеграции с внешними системами на примере управления персоналом
А operationid где потом используется?
Отличный вопрос, я его ждал:)
Я знаю 2 варианта.
1ый - используется при автогенерации кода по спецификации для наименования методов. Если operationId = getToyById, то в коде соответствующий метод будет похож на ResponseEntity getToyById(...) {...}. Если интересны детали, то предлагаю посмотреть мое видео про генерацию: ua-cam.com/video/HAGSYTN7lZQ/v-deo.html
2ой - используется для якорей в документации, так как значение operationId должно быть уникальным среди всех методов.
Подскажите а как работает OpenAPI вместе с OAuth (3)?
Точно вопрос про версию OAuth 3? Последняя на данный момент 2.1.
А если все-таки цель подружить OpenAPI 3 с OAuth 2, то я советую вам посмотреть на их документацию в первую очередь. Там с примерами. swagger.io/docs/specification/authentication/oauth2/
А метод POST /toys/(toy_id) может быть создан?
Да, может. Но если идентификатор генерируется на строне сервера, то лучше делать просто POST /toys.
А так можно делать хоть get /toys/{id}, который будет удалять эту игрушку:) Ограничений, кроме адекватности нет.
Как сделать так что бы в Схеме можно было указывать несколько игрушек? Практиковался на вашем примере но постоянно выдавало ошибку "duplicated mapping key"
Не совсем понял Ваш вопрос. В каком именно месте вы хотите несколько игрушек? Где примеры, или хотите передать массив игрушек в какой-то метод?
@@IT_like_bricks_building
В целом да, чтобы несколько игрушек отображались в методе (в интерфейсе справа).
Допустим я хочу добавить ещё одну игрушку, и чтобы она тоже отображалась в результате успешного запроса. Ну там "Train" и например "Car". При попытке сделать новый объект в "компонентах" у меня либо появлялась эта ошибка о дублировании, либо о том что "объект" ещё не дописан. В любом случае, справа в результате запроса, появлялась только одна из двух созданных мной игрушек.
Как сделать так чтобы можно было показать весь перечень объектов (игрушек), которые записаны в компонентах?
У меня получилось так сделать только если описывал их прямо в "path", но тогда создавать ссылки нельзя.
Буду признателен за помощь.
Кажется, я понял, о чем был вопрос.
В разделе "paths" есть возможность использовать "examples", посмотрите на возвращаемое значение у метода get /toys в случае успеха. Там поезд и самолет возвращаются. Но это пример под конкретный метод, что не есть универсально.
А вот в разделе "components" нет возможности использовать "examples", только "example". Покрутил, попробовал, ничего дельного не смогу посоветовать, не придумал.
а есть ли у Вас опыт автоматизации тестирования API через Insomnia? Может быть поделитесь своим опытом / лайфхаками
Автоматизацию через insomnia мы не делали. Мы сразу пошли по пути использования спец приложений, например, dredd (есть видео на канале) и microcks (более современен)
@@IT_like_bricks_building т.е по вашему опыту (опыт вашей команды), на текущий момент автоматизацию тестирования API лучше всего реализовывать через dredd и microcks, чем на том же постман / инсомния или на Java с использованием Rest assured?
Мне кажется, что если мы говорим про автоматизацию, то нам всем хотелось бы, чтобы сами тесты +/- автоматически генерировались по имеющейся OpenApi спецификации. Поэтому я бы выбирал те инструменты, которое это умеют из коробки делать.
Postman вроде бы умеет работать со спецификацией (генерировать коллекцию запросов по ней), у нас в одном из проектов как раз на нем тесты и сделаны. Но там руками много всего вносится нового, поэтому я бы не назвал это автоматизацией, хотя может мы не докрутили где-то.
Insomnia для авто тестов мне не особо понравилась, хотя она тоже генерирует коллекцию запросов по спецификации.
Dredd и Microcks прям специализируются на решении обсуждаемой нами задачи, только dredd не полностью поддерживает 3ю версию OpenApi.
Rest Assured, как я вижу, тоже не особо дружит с автогенерацией тестов, хотя, может, доп плагинами проблема и решается.
В общем если начинать новый проект, я бы использовал Microcks. А ещё лучше сразу Apicurio для проектирования спецификаций, внутри которого уже встроен Microcks для тестов:)
@@IT_like_bricks_building благодарю за расширенный ответ) буду ждать новые видео)
Добрый день, подскажите пожалуйста, как описывать обязательные header - ы. Необходимо в некоторых (не всех) запросах вставлять хидером сессионный ключ авторизации. Что-то читаю документацию, гуглю, вставляю все в редактор сваггера и ничего не получается. Пытаюсь составить доку в версии 3.0.3, пример находил в версии 1.0.0. Не заработало, может быть из-за версии. Три часа провозился и никакого результата. Сейчас остановился на следующем:
paths:
/toys:
post:
requestBody: ...
responses: ...
parameters:
- session_key:
$ref: "#/components/headers/session_key_header"
components:
schemas: ...
headers:
session_key_header:
description: ...
schema:
type: string
Добрый день. Вроде бы рекомендуется использовать components/parameters для этого.
Посмотрите на эту страницу, мне кажется, это то, что вы ищете github.com/swagger-api/swagger-editor/issues/1827
@@IT_like_bricks_building спасибо
так, а как получившееся описание использовать-то? что сделать чтобы на моем сервере так же красиво открывалось как в редакторе?
Использований много, начиная от красивого описания, заканчивая кодогенерацией. Подтяните зависимость swagger-ui к вашему проекту
swagger ui
@@IT_like_bricks_building Подскажите как подтянуть? как сделать так, что документация была в моем проекте по определенному урлу, приложение написано раньше чем дока, вот теперь сформированную доку в editore нужно как-то разместить в проекте, по определенной ссылке, подскажите как??? пожалуйста!
Немного поздно заметил вопрос, думаю, вы уже справились. Но ответ таков, что подключаем в проект зависимость swagger ui, и там указываем путь к спецификации. По итогу при старте модуля на url:port/swagger-ui/index.html (вроде бы так) откроется ваша спецификация
понятно говоришь)
Спасибо!
Огромное вам спасибо, я нашел много роликов, но только вы так четко, кратко и точно описали все методы, получилось с первого раза. Подскажите пожалуйста, а можно ли через такую спецификацию описывать зависимости между @Entiey для Hibernate ?
Рад, что видео было полезным для вас!
А ответ на ваш вопрос, честно говоря, не знаю, не пробовал. Если вы уже выяснили, напишите, пожалуйста. Вдруг кому-то пригодится.
@@IT_like_bricks_building Выяснил, нельзя, это ни как несвязанные сущности.
Спасибо!
На самом деле можно использовать генератор документации. В FastAPI такое есть.
Все верно. Если идти по пути сначала код, а потом авто генерация спецификации, то да, ваш вариант как раз то, что нужно.
А вот если наоборот, то придется ручками написать) Хотя и тут есть упрощения. Можно использовать конструкторы спецификации, например, Apicurio (когда-нибудь сделаю видео по нему).
@@IT_like_bricks_building а в чем разница между автоматической и ручной спецификации? Написал апи, хочу спецификацию сделать к нему, вот думаю, сделать через генерацию или самому прописать все.
Разница именно в подходе.
В некоторых проектах команда идёт по пути, когда сначала аналитик проектирует и создаёт спецификацию, а затем разработчик разрабатывает по ней или автоматом генерирует код по спецификации.
В некоторых компаниях делают наоборот. Пишут код, помечают методы аннотациями и тд, бонусом получают спецификацию при сборке.
@@IT_like_bricks_building понял, спасибо!
Спасибо вам большое, вся информация изложена очень обстоятельно и доступным языком.
Будьте добры, подскажите как я могу проверить написанную спецификацию, например создать игрушку, потом запросить список игрушек или описание игрушки по ее id?
При этом цель просто проверить, что все ошибки, атрибуты и т.д. в спецификации указаны правильно. То есть если я правильно понимаю, нужен локальный сервис созданный по спецификации (причем не важно на каком языке, я не разработчик, я просто проектирую спецификацию). В идеале в Docker. Насколько я понимаю такой класс продуктов называется Mock сервера, но я не смог найти ни один который бы понял спецификацию Swagger Petstore - OpenAPI 3.0 (демо спецификация) - просто на ней тестировал исходя из того что уж она точно написана по стандарту.
Данное видео (ua-cam.com/video/HAGSYTN7lZQ/v-deo.html) но там к сожалению уже сложно и описывается как модифицировать код серверной части. К сожалению уже сложно да и как автор говорит даже те правки по небольшой схеме это только самое начало тех ошибок с которыми придется столкнуться. Кажется получается слишком трудоемко чтобы просто проверить что в спецификации нет ошибок.
Огромное спасибо за фидбек!
Могу посоветовать для ваших нужд Prism ( stoplight.io/open-source/prism ), лично я не использовал, но слышал очень хорошие отзывы.
Еще рекомендую отличный сайт openapi.tools/ , там есть много всего полезного для OpenAPI. В частности раздел "Mock Servers", там и Prism, и много других. Я как-то использовал в одном из видео Mocklab для тестов спецификации, в целом было нормально.
@@IT_like_bricks_building Спасибо, попробую
что такое OperationID? 3:40
Я ниже в комментариях уже отвечал на аналогичный вопрос, значение атрибута будет использовано при генерации кода по спецификации. Оно станет названием соответствующего метода в коде.
@@IT_like_bricks_building Спасибо увидел!))
а для чего нужен этот конструктор? Просто поиграться?
Не нашел никакой информации в инете как его можно привязать к Api, что б вместо автоматически сгенерированной документации, отобаражалсь она
Я не понял вопроса скорее всего. OpenApi - это описание api сервиса, один из вариантов его четкого однозначного описания машинным языком и одновременно человеческим.
По генерации есть два варианта. По коду сервиса строить спецификацию или наоборот по спецификации код генерировать.
MOLODETS
очень тихо((
Слишком быстро все делаете. Ощущение, что это урок не для новичка. За вами не угнаться, когда видишь свагер в первый раз.
Спасибо) на самом деле я думал об этом, когда монтировал видео. Но подумал, что это лучше, чем много воды и долго. Коротко и по делу))
Попробуйте принять основную мысль, которую я пытался вложить в видео. Документация не так страшна, как может показаться в первый раз.
И делайте паузы. Успехов вам в обучении!
@@IT_like_bricks_building паузы и многократные перемотки назад мне помогают😅
Спасибо!)
Мне по скорости нормально, возможно тяжело вникать без хорошего понимания rest-api
(Пишу без негатива, просто мысли😊)
Да нихрена не информативно.
С первых же секунд не понятно, где автор нашёл документацию ??? - на главной странице нет никакой ссылки ! Хорошо что Гугл знает, где она находится.
Второй вопрос - Где автор нашёл эдитор ?
Не плохо бы объяснить, т.к. с главной страницы мы попадаем на репозиторий ГитХаб и что с ним делать, нигде не написано - говорят лишь, есть такие во скрипты, а как это приложение запускать ?!
Это позор для тех, кто создал такое приложение и так представляет информацию пользователям. И странно что автор видео совершенно не замечает этих проблем.
Спасибо большое. Очень понятно рассказываешь.
Спасибо за фидбек, для меня это важно!
Спасибо!
четко и понятно, спасибо!
есть разбор оформления документации по АПИ Аналитиками для разработчиков: к примеру, описали мы в сваггере АПИ, что дальше с этим делать?
Достаточно ли разработке ссылки (на сваггер) на данный формат описания АПИ?
Ссылки достаточно для разработчиков. Там исчерпывающая инфа для создания Api. Останется только бизнес логику описать, то есть какие действия модуль делает при получении определенного запроса
@@IT_like_bricks_building
Спасибо большое от системного аналитика!