Установка и настройка Swagger

December 20, 2016 Jazz Team Технические статьи

Описание

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-сервисе и возможности отправки запроса.

REST, REST-сервисы, Swagger, мануал, техническая статья

Лучшие практики использования Mule ESB С наступающим Новым 2017 годом и Рождеством!