У даній статті я розповім як підключити Swagger до Maven проекту, в якому реалізовані REST-сервесе за допомогою реалізації специфікації JAX-RS - RESTEasy. У статті буде розписано підключення Swagger до проекту, використання документування REST-сервісів за допомогою анотацій, опис візуалізації документації через Web UI.
Підключення Swagger до проекту
Підключення Maven залежностей
Для початку ми повинні додати в проект Maven залежність Swagger'а. Так як ми буде підключати Swagger до RESTEasy, то додамо відповідну залежність.
На момент написання мануала актуальною версією є 1.5.6.
Потрібно врахувати, що у Swagger є legacy maven репозиторій. У lagecy сховища groupId = com.wordnik. Потрібно це врахувати і не переплутати залежності!
Більш докладно можна прочитати тут.
Налаштування проекту
Далі нам необхідно підключити до проекту необхідних слухачів (listeners), щоб Swagger міг автоматично визначати анотації і генерувати документацію.
Ми виробляли настройку за допомогою нащадка класу javax.ws.rs.core.Application.
Налаштування буде виглядати так:
Більш докладно про інші методи підключення можна почитати тут.
Налаштування Swagger
Далі необхідно встановити настройки самого Swagger. Ми це зробили в конструкторі того ж спадкоємця класу Application.
Більш докладно про інші методи настройки можна прочитати тут.
Для початку я опишу анотації, які є обов'язковими для правильного документування та коректного відображення REST-сервісів на Swagger-UI.
Для того, щоб swagger визначив, що в класі знаходяться REST-сервіси, цей клас повинен бути позначений анотацією @Api. В параметрах цієї інструкції можна вказати назву розділу, в якому будуть знаходиться REST'и в UI, і вказати опис даного розділу.
наприклад:
@ApiOperation
Анотацію @ApiOperation необхідно вказувати над методом REST-сервісу. Також в її параметрах можна вказати опис сервісу.
інші анотації
Для явного вказівки Хідер, які є обов'язковими для конкретного сервісу можна використовувати анотацію
Для явного вказівки об'єкта відповіді можна використовувати анотацію @ApiResponse. Це буде корисно, якщо в якості відповіді від сервера REST повертає об'єкт Responce.
Більш детальну інформацію про всі анотаціях можна знайти тут.
Щоб встановити url за замовчуванням необхідно відредагувати вихідний код файлу index.html
Після чого ми побачимо документацію наших REST-сервісів. Робити запити до REST-сервісів можна прямо з UI.
У разі якщо Swagger видасть помилку can`t fetch потрібно буде робити настроювання CORS headers в сервері, на якому задеплоено наш додаток, нам потрібно додати header Access-Control-Allow-Origin: *
Приклад відображення REST-сервісів на UI:
Список REST сервісів на Web-UI:
Форма детальної інформації про REST-сервісі і можливості відправки запиту.