Хабр Курсы для всех
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 8
Сравнивали с springfox-swagger2? Если да, то что вам показалось лучше? Задачи ведь практически одни и те же.
Это очень хороший вопрос, на самом деле, я специально не делал в этой статье сравнение со swagger либо другим инструментом документирования, чтобы не показаться необъективным, основная идея была сделать ознакомление с TDD и springrestdocs.
В двух словах об отличиях:
springrestdocs
springfox
Я не евангелист/адвокат какой либо из технологий, как профессионалы, мы должны знать и уметь применить нужный инструмент к нужной прикладной задаче. Всё зависит от Вашего частного случая, если вы работаете в spring экосистеме сюда идеально вписывается spirngrestdocs.
Но если у вас полиглотная система — например есть симбиоз микросервисов на spring, node, python либо других языках, то есть смысл конечно же использовать единый стандарт для их документирования — swagger, это невероятно мощный инструмент. К тому же сваггер позволяет генерировать сервервный/клиентский код, стабы исходя из файла спецификации. И здесь Вам стоит посмотреть на его новую версию OpenAPI3.0 в которой наконец появились новые фичи такие как документирование HATEOAS.
Можете посмотреть мой доклад — он больше построен на сравнение swagger со spring-rest-docs TDD with SrpingRestDocs
В двух словах об отличиях:
springrestdocs
- генерит документацию из тестов, в случае её несоответствия логике приложения вы получаете мгновенную реакцию — падающие тесты с детальным сообщением о разнице. Т.е. гарантируется целостность
- Также формат asciidoc позволяет вести документацию в гибком формате удобном для нас (включение ресурсов, добавление текстовых секция либо файлов из classpath, переформатирование в pdf, epub и прочие), мы не ограничены стандартной страничкой свагера
- Вы вводите методологию работы по Test Driven Documentation подходу (модификация классического TDD). Вы и Ваши коллеги будете писать больше тестов, по началу будет определённый переломный период адаптации у людей в команде, которые раньше не «особо часто» применяли тесты. Но через небольшое число итераций они уже подсознательно будут работать по TDD не только при написании REST эндпоинтов, но и в остальных аспектах разработки
springfox
- необычайно легок в применении, удобен для поднятия свагера в spring-based проекте (минимум усилий).
- Springfox-swagger2 создает дополнительный json-эндпоинт спецификации и, если подключен springfox-swagger-ui, то и страничку swagger документации.
Кстати, можете посмотреть в github моем github repo также лежит пример с использованием springfox.
Я не евангелист/адвокат какой либо из технологий, как профессионалы, мы должны знать и уметь применить нужный инструмент к нужной прикладной задаче. Всё зависит от Вашего частного случая, если вы работаете в spring экосистеме сюда идеально вписывается spirngrestdocs.
Но если у вас полиглотная система — например есть симбиоз микросервисов на spring, node, python либо других языках, то есть смысл конечно же использовать единый стандарт для их документирования — swagger, это невероятно мощный инструмент. К тому же сваггер позволяет генерировать сервервный/клиентский код, стабы исходя из файла спецификации. И здесь Вам стоит посмотреть на его новую версию OpenAPI3.0 в которой наконец появились новые фичи такие как документирование HATEOAS.
Можете посмотреть мой доклад — он больше построен на сравнение swagger со spring-rest-docs TDD with SrpingRestDocs
Спасибо за столь развернутый ответ!
Вот еще на stackoverflow нашел обсуждение. Правда оно датируются началом 2016 года. Там так же есть ссылка на видео о разных инструмента документирования, в том числе и о Swagger.
Соглашусь, что со springRestDocs прививать tdd одно удовольствие) Однако, как раз о swagger я почему то слышал больше, чем о springRestDocs.
Вот еще на stackoverflow нашел обсуждение. Правда оно датируются началом 2016 года. Там так же есть ссылка на видео о разных инструмента документирования, в том числе и о Swagger.
Соглашусь, что со springRestDocs прививать tdd одно удовольствие) Однако, как раз о swagger я почему то слышал больше, чем о springRestDocs.
Все верно и не удивительно что слышали больше о swagger — он давно на рынке и широко используется, и он охватывает 25 языков программирования (генерация кода), теперь он мигранул в OpenAPI3.0, в ближайшие годы именно это название будет звучать вместо swagger.
SpringRestDocs относительно недавнее свежее решение и его удобно использовать в spring экосистеме, в то время как OpenAPI3.0 применим везде (но без TDD).
Отсюда и диспропорция — во времени существования продуктов, охвата языков.
Пока нет «серебряной пули»
SpringRestDocs относительно недавнее свежее решение и его удобно использовать в spring экосистеме, в то время как OpenAPI3.0 применим везде (но без TDD).
Отсюда и диспропорция — во времени существования продуктов, охвата языков.
Пока нет «серебряной пули»
Слишком много действий чтобы просто посмотреть весть REST API бэка. Что насчет Springfox Swagger UI?
Под maven получится сконфигурировать тоже самое, что описано для gradle?
Под maven получится сконфигурировать тоже самое, что описано для gradle?
Если Вы используете maven — все описанное актуально. Чем мне нравится спринговая документация docs.spring.io/spring-restdocs/docs/current/reference/html5 — в ней приведены конфиги для gradle/maven более того, конкретно для springrestdocs также есть примеры тестов с использованием MockMvc/RestAssured. Что юзать — Ваше предпочтение или специфика проекта, команды, организации.
На самом деле эти действия необходимо произвести только один раз при настройке проекта, более того можно воспользоваться дефолтной конфигурацией (меньше кода, конфиг со старта).
Здесь речь идет не только о просмотре REST API, а о гарантированности его соответствия, написания тестов, кастомизации документации, включении в неё диаграмм, ресурсов, генерации офлайн мультиформатных версий.
Это нереально включить в одну статью (она будет перегружена материалом), поэтому, если тема будет пользоваться интересом — я однозначно опишу в следующих частях все перечисленные плюшки и разберу их на практических примерах.
Здесь речь идет не только о просмотре REST API, а о гарантированности его соответствия, написания тестов, кастомизации документации, включении в неё диаграмм, ресурсов, генерации офлайн мультиформатных версий.
Это нереально включить в одну статью (она будет перегружена материалом), поэтому, если тема будет пользоваться интересом — я однозначно опишу в следующих частях все перечисленные плюшки и разберу их на практических примерах.
На скриншоте
Пример документации метода Get All Speakersесть описание для параметра id метода, возможно это есть в статье, но я не увидел, каким образом это делается?
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Документируем и тестируем REST API с помощью SpringRestDocs