Документация Spring REST API с использованием Swagger
Я ищу инструмент, который мог бы помочь мне сгенерировать документацию RESTful API. Мой сервер написан на Java и использует инфраструктуру Spring MVC. У меня нет просмотров на моем сервере. Это 100% RESTful-сервис, и все, что он делает, это потребляет JSON и выплевывает JSON.
Мне было интересно, совместим ли Swagger с аннотациями Spring?
5 ответов
В настоящее время недоступен модуль swagger Spring MVC (по крайней мере, из Wordnik), но в целом включить swagger в REST-сервисе на основе JVM довольно просто.
Поддержка сервера Swagger разделена на две части - главный сервер и интеграция со службой REST. Смотрите репозиторий Swagger Github. Ядро Swagger определяет документ, который представляет службу REST, параметры, допустимые значения, операции HTTP и т. Д. Серверная интеграция связывает этот документ со структурой инфраструктуры REST. Wordnik использует Джерси через JAX-RS и выпустил swagger-jaxrs для этой интеграции. Существует также модуль Swagger-Play, который вскоре будет выпущен в репозиторий модуля Play.
Если вы хотите включить swagger в другой среде REST (например, Spring MVC), выполните следующие действия:
1) Сгенерируйте API Reader для создания объекта com.wordnik.swagger.core.Documentation. Смотрите версию JAX-RS, а также версию для игры.
2) Создайте конечную точку REST, которая возвращает JSON/XML-версию объекта Documentation клиенту. Опять JAX-RS и игра.
3) Добавьте фильтр для перехвата запросов для обеспечения доступа к ресурсам или объектам.
Короче говоря, его можно довольно легко собрать.
Здесь идет реализация Swagger-SpringMVC и примеры здесь.
Спецификация v1.2 полностью реализована и поддерживается (т. Е. Модели генерируются с полной поддержкой обобщений), и она находится в активной разработке.
Другая реализация Swagger для Spring MVC - это swagger4spring-web.
Он похож на Swagger-SpringMVC и поддерживает все аннотации Swagger и генерирует схему JSON для возвращаемых типов и параметров. Это также работает без чванских аннотаций.
Если вы только после создания интерактивного документа API (без необходимости совместной работы в стиле вики), документы ввода / вывода будут лучшим решением, требующим гораздо меньших усилий по настройке, использованию и настройке, IMHO.
Он работает на nodejs и Redis. Вам нужно только написать JSON-схему вашего API, и он генерирует сайт HTML/JS, который описывает ваш API и позволяет разработчикам играть с ним в реальном времени из своего браузера.
Я планирую разместить свой API на своем сервере (так как требовать от кого-либо установки 2 других программ просто для просмотра API - это безумие), но сама схема JSON уже имеет приятную для чтения и компактную структуру, которую, я думаю, будет достаточно для совместной работы с другими программисты. Это маленький проект.
Есть похожий вопрос, который вы можете проверить.
Swagger 2.0 является последней версией Swagger.
В настоящее время существуют различные варианты Swagger для различных нужд.
io.swagger это пакет для библиотек Swagger, и вам нужны отдельные JAR-файлы Spring, чтобы связать его с Spring. Это версия 2 чванства.
io.springfox Springfox Swagger2, в котором Swagger интегрирован с Spring.
com.mangofactory swagger интегрирован со средой Spring Web MVC.