Установка и настройка Swagger
Описание
Swagger – это технология, которая позволяет документировать REST-сервисы. Swagger поддерживает множество языков программирования и фреймворков. Также Swagger предоставляет UI для просмотра документации.
В данной статье я расскажу как подключить Swagger к Maven проекту, в котором реализованы REST-сервисы с помощью спецификации JAX-RS – RESTEasy. В статье будет расписано подключение Swagger к проекту, использование документирования REST-сервисов с помощью аннотаций, описание визуализации документации через Web UI.
Подключение Swagger к проекту
Подключение Maven зависимостей
Для начала мы должны добавить в проект Maven зависимость Swagger’а. Так как мы будет подключать Swagger к RESTEasy, то добавим соответствующую зависимость.
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jaxrs</artifactId>
<version>1.5.6</version>
</dependency>
На момент написания мануала актуальной версией является 1.5.6.
Нужно учесть, что у Swagger есть legacy Maven репозиторий. У lagecy репозитория groupId=com.wordnik. Нужно это учесть и не перепутать зависимости!
Более подробно можно прочитать тут.
Настройка проекта
Далее нам необходимо подключить в проект необходимых слушателей (listeners), чтобы Swagger мог автоматически определять аннотации и генерировать документацию.
Мы производили настройку с помощью потомка класса javax.ws.rs.core.Application.
Настройка будет выглядеть так:
public class SampleApplication extends Application {
@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> resources = new HashSet();
resources.add(io.swagger.jaxrs.listing.ApiListingResource.class);
resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);
return resources;
}
}
Более подробно о других методах подключения можно почитать тут.
Настройка Swagger
Далее необходимо установить настройки самого Swagger. Мы это сделали в конструкторе того же наследника класса Application.
public class SampleApplication extends Application {
public SampleApplication() {
BeanConfig beanConfig = new BeanConfig();
beanConfig.setVersion("1.0.0");
beanConfig.setBasePath("/api");
beanConfig.setResourcePackage("org.jazzteam");
beanConfig.setScan(true);
}
@Override
public Set<Class<?>> getClasses() {
Set<Class<?>> resources = new HashSet();
resources.add(io.swagger.jaxrs.listing.ApiListingResource.class);
resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);
return resources;
}
}
Более подробно о других методах настройки можно прочитать тут.
После всех настроек информация о приложении должна быть доступна по ссылке http://localhost:8080/api/swagger.json. Есть также возможность вывода информации в YAML-формате (для этого нужно поменять в ссылке JSON на YAML)
Аннотации
Для начала я опишу аннотации, которые являются обязательными для правильного документирования и корректного отображения REST-сервисов на Swagger-UI.
@Api
Для того, чтобы swagger определил, что в классе находятся REST-сервисы, этот класс должен быть помечен аннотацией @Api. В параметрах данной аннотации можно указать название раздела, в котором будут находится REST’ы в UI, и указать описание данного раздела.
Например:
@Api(value = "Account", description = "APIs for working with users")
public class AccountRestService {...}
@ApiOperation
Аннотацию @ApiOperation необходимо указывать над методом REST-сервиса. Также в её параметрах можно указать описание сервиса.
@Path("login")
@POST
@ApiOperation(value = "Login")
public Response login() {...}
Другие аннотации
Для явного указания хидеров, которые являются обязательными для конкретного сервиса можно использовать аннотацию @ApiImplicitParam
@Path("logout")
@POST
@ApiOperation(value = "Logout")
@ApiImplicitParams({
@ApiImplicitParam(name = "Authorization", paramType = "header",
dataType = "string",required = true,
defaultValue = "Token <paste_token_here>")
})
public Response logout() {...}
Для явного указания объекта ответа можно использовать аннотацию @ApiResponse. Это будет полезно, если в качестве ответа от сервера REST возвращает объект Responce.
@Path("login")
@POST
@ApiOperation(value = "Login")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "OK", response = Token.class)
})
public Response login() {...}
Более подробную информацию обо всех аннотациях можно найти тут.
WEB UI
Для визуализации необходимо выкачать данный проект https://github.com/swagger-api/swagger-ui.
В директории dist будет находиться файлик index.html, нам нужно его открыть.
Далее в верхнее поле для ввода нам необходимо ввести вышеупомянутый url http://localhost:8080/api/swagger.json и нажать кнопку Explore.
Чтобы установить url по умолчанию необходимо отредактировать исходный код файла index.html
После чего мы увидим документацию наших REST-сервисов. Делать запросы к REST-сервисам можно прямо из UI.
В случае если Swagger выдаст ошибку can`t fetch нужно будет производить настройку CORS headers в сервере, на котором задеплоено наше приложение, нам нужно добавить header Access-Control-Allow-Origin:*
Пример отображения REST-сервисов на UI:
Список REST сервисов на Web-UI:
Форма детальной информации о REST-сервисе и возможности отправки запроса.
Лучшие практики использования Mule ESB С наступающим Новым 2017 годом и Рождеством!