Как настроить swagger
Перейти к содержимому

Как настроить swagger

  • автор:

Swagger (OpenAPI 3.0)

Всем привет. Это мой первый пост на Хабре и я хочу поделиться с вами своим опытом в исследовании нового для себя фреймворка.

Мне предоставился момент выбрать тему и подготовить презентацию для своей команды. Вдохновившись спикером Евгений Маренковым, я решил выбрать данную тему. В процессе подготовки, я облазил много статей и репозиториев, чтобы компактно и эффективно донести нужную информацию.

Сейчас хочу поделиться ею в надежде, что кому-то она поможет в изучение Swagger (OpenApi 3.0)

Введение

Я на 99% уверен у многих из вас были проблемы с поиском документации для нужного вам контроллера. Многие если и находили ее быстро, но в конечном итоге оказывалось что она работает не так как описано в документации, либо вообще его уже нет.
Сегодня я вам докажу, что есть способы поддерживать документацию в актуальном виде и в этом мне будет помогать Open Source framework от компании SmartBear под названием Swagger, а с 2016 года он получил новое обновление и стал называться OpenAPI Specification.

Swagger — это фреймворк для спецификации RESTful API. Его прелесть заключается в том, что он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы – так называемый Swagger UI.

Также возможно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого понадобится Swagger Codegen.

Основные подходы

Swagger имеет два подхода к написанию документации:

  • Документация пишется на основании вашего кода.
    • Данный подход позиционируется как «очень просто». Нам достаточно добавить несколько зависимостей в проект, добавить конфигурацию и уже мы будем иметь нужную документацию, хоть и не настолько описанной какою мы хотели.
    • Код проекта становится не очень читабельным от обилия аннотаций и описания в них.
    • Вся документация будет вписана в нашем коде (все контроллеры и модели превращаются в некий Java Swagger Code)
    • Подход не советуют использовать, если есть возможности, но его очень просто интегрировать.
    • Данный подход требует знать синтаксис Swagger Specification.
    • Документация пишется либо в YAML/JSON файле, либо в редакторе Swagger Editor.

    Swagger Tools

    Swagger или OpenAPI framework состоит из 4 основных компонентов:

    1. Swagger Core — позволяет генерировать документацию на основе существующего кода основываясь на Java Annotation.
    2. Swagger Codegen — позволит генерировать клиентов для существующей документации.
    3. Swagger UI — красивый интерфейс, который представляет документацию. Дает возможность просмотреть какие типы запросов есть, описание моделей и их типов данных.
    4. Swagger Editor — Позволяет писать документацию в YAML или JSON формата.

    Теперь давайте поговорим о каждом компоненте отдельно.

    Swagger Core

    Swagger Code — это Java-реализация спецификации OpenAPI

    Для того что бы использовать Swagger Core во все орудие, требуется:

    • Java 8 или больше
    • Apache Maven 3.0.3 или больше
    • Jackson 2.4.5 или больше

    Что бы внедрить его в проект, достаточно добавить две зависимости:

     io.swagger.core.v3 swagger-annotations 2.1.6  org.springdoc springdoc-openapi-ui 1.5.2 

    Также можно настроить maven плагин, что бы наша документация при сборке проект генерировалсь в YAML

     org.springdoc springdoc-openapi-maven-plugin 0.3  integration-test generate    http://localhost:8080/v3/api-docs openapi.yaml $ 

    Дальше нам необходимо добавить конфиг в проект.

    Для конфигурации Swagger необходимо добавить два бина. Где нам нужно будет описать название приложения, версию нашего API, так же можно добавить контакт разработчика, который отвечает за данные API.

     @Bean public GroupedOpenApi publicUserApi() < return GroupedOpenApi.builder() .group("Users") .pathsToMatch("/users/**") .build(); >@Bean public OpenAPI customOpenApi(@Value("$")String appDescription, @Value("$")String appVersion) < return new OpenAPI().info(new Info().title("Application API") .version(appVersion) .description(appDescription) .license(new License().name("Apache 2.0") .url("http://springdoc.org")) .contact(new Contact().name("username") .email("test@gmail.com"))) .servers(List.of(new Server().url("http://localhost:8080") .description("Dev service"), new Server().url("http://localhost:8082") .description("Beta service"))); >

    После добавления нужных нам зависимостей, у нас появятся новые аннотация с помощью которых можно документировать наш код.

    Вот некоторые из них:

    • @Operation — Описывает операцию или обычно метод HTTP для определенного пути.
    • @Parameter — Представляет один параметр в операции OpenAPI.
    • @RequestBody — Представляет тело запроса в операции
    • @ApiResponse — Представляет ответ в операции
    • @Tag — Представляет теги для операции или определения OpenAPI.
    • @Server — Представляет серверы для операции или для определения OpenAPI.
    • @Callback — Описывает набор запросов
    • @Link — Представляет возможную ссылку времени разработки для ответа.
    • @Schema — Позволяет определять входные и выходные данные.
    • @ArraySchema — Позволяет определять входные и выходные данные для типов массивов.
    • @Content — Предоставляет схему и примеры для определенного типа мультимедиа.
    • @Hidden — Скрывает ресурс, операцию или свойство
    @Tag(name = "User", description = "The User API") @RestController public class UserController <>
     @Operation(summary = "Gets all users", tags = "user") @ApiResponses(value = < @ApiResponse( responseCode = "200", description = "Found the users", content = < @Content( mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserApi.class))) >) >) @GetMapping("/users") public List getUsers()

    Swagger Codegen

    Swagger Codegen — это проект, который позволяет автоматически создавать клиентские библиотеки API (создание SDK), заглушки сервера и документацию с учетом спецификации OpenAPI.

    В настоящее время поддерживаются следующие языки / фреймворки:

    • API clients:
      • Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured)
      • Kotlin
      • Scala (akka, http4s, swagger-async-httpclient)
      • Groovy
      • Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations)
      • Haskell (http-client, Servant)
      • C# (.net 2.0, 3.5 or later)
      • C++ (cpprest, Qt5, Tizen)
      • Bash
      • Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST)
      • Kotlin
      • C# (ASP.NET Core, NancyFx)
      • C++ (Pistache, Restbed)
      • Haskell (Servant)
      • PHP (Lumen, Slim, Silex, Symfony, Zend Expressive)
      • Python (Flask)
      • NodeJS
      • Ruby (Sinatra, Rails5)
      • Rust (rust-server)
      • Scala (Finch, Lagom, Scalatra)
      • HTML
      • Confluence Wiki
      • JMeter

      Что бы внедрить его в проект, достаточно добавить зависимость, если используете Swagger:

       io.swagger swagger-codegen-maven-plugin 2.4.18 

      и если используете OpenApi 3.0, то:

       io.swagger.codegen.v3 swagger-codegen-maven-plugin 3.0.24 

      Можно настроить maven плагин, и уже на процессе сборки мы можем сгенерировать нужный для нас клиент либо мок сервиса.

        org.openapitools openapi-generator-maven-plugin 3.3.4  compile generate  spring $/src/main/resources/api.yaml $/generated-sources com.api com.model ApiUtil.java $ $ $ true swagger spring-mvc true true java8 true  $/.openapi-generator-ignore    

      Также все это можно выполнить с помощью командной строки.

      Запустив джарник codegen и задав команду help можно увидеть команды, которые предоставляет нам Swagger Codegen:

      • config-help — Справка по настройке для выбранного языка
      • generate — Сгенерировать код с указанным генератором
      • help — Отображение справочной информации об openapi-generator
      • list — Перечисляет доступные генераторы
      • meta — Генератор для создания нового набора шаблонов и конфигурации для Codegen. Вывод будет основан на указанном вами языке и будет включать шаблоны по умолчанию.
      • validate — Проверить спецификацию
      • version — Показать информацию о версии, используемую в инструментах

      Для нас самые нужные команды это validate, которая быстро проверять на валидность спецификации и generate, с помощью которой мы можем сгенерировать Client на языке Java

      • java -jar openapi-generator-cli-4.3.1.jar validate -i openapi.yaml
      • java -jar openapi-generator-cli-4.3.1.jar generate -i openapi.yaml -g java —library jersey2 -o client-gener-new

      Swagger UI

      Swagger UI — позволяет визуализировать ресурсы API и взаимодействовать с ними без какой-либо логики реализации. Он автоматически генерируется из вашей спецификации OpenAPI (ранее известной как Swagger), а визуальная документация упрощает внутреннюю реализацию и использование на стороне клиента.

      Вот пример Swagger UI который визуализирует документацию для моего pet-project:

      Нажавши на кнопку «Try it out», мы можем выполнить запрос за сервер и получить ответ от него:

      Swagger Editor

      Swagger Editor — позволяет редактировать спецификации Swagger API в YAML внутри вашего браузера и просматривать документацию в режиме реального времени. Затем можно сгенерировать допустимые описания Swagger JSON и использовать их с полным набором инструментов Swagger (генерация кода, документация и т. Д.).

      На верхнем уровне в спецификации OpenAPI 3.0 существует восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов, но на верхнем уровне есть только следующие объекты:

      1. openapi
      2. info
      3. servers
      4. paths
      5. components
      6. security
      7. tags
      8. externalDocs

      Для работы над документацией со спецификацией используется онлайн-редактор Swagger Редактор Swagger имеет разделенное представление: слева пишем код спецификации, а справа видим полнофункциональный дисплей Swagger UI. Можно даже отправлять запросы из интерфейса Swagger в этом редакторе.

      Редактор Swagger проверит контент в режиме реального времени, и укажет ошибки валидации, во время кодирования документа спецификации. Не стоит беспокоиться об ошибках, если отсутствуют X-метки в коде, над которым идет работа.

      Первым и важным свойством для документации это openapi. В объекте указывается версия спецификации OpenAPI. Для Swagger спецификации это свойство будет swagger:

       openapi: "3.0.2"

      Объект info содержит основную информацию о вашем API,включая заголовок, описание, версию, ссылку на лицензию, ссылку на обслуживания и контактную информацию. Многие из этих свойство являются не обязательными.

      info: title: "OpenWeatherMap API" description: "Get the current weather, daily forecast for 16 days, and a three-hour-interval forecast for 5 days for your city." version: "2.5" termsOfService: "https://openweathermap.org/terms" contact: name: "OpenWeatherMap API" url: "https://openweathermap.org/api" email: "some_email@gmail.com" license: name: "CC Attribution-ShareAlike 4.0 (CC BY-SA 4.0)" url: "https://openweathermap.org/price"

      Объект servers указывает базовый путь, используемый в ваших запросах API. Базовый путь — это часть URL, которая находится перед конечной точкой. Объект servers обладает гибкой настройкой. Можно указать несколько URL-адресов:

      servers: - url: https://api.openweathermap.org/data/2.5/ description: Production server - url: http://beta.api.openweathermap.org/data/2.5/ description: Beta server - url: http://some-other.api.openweathermap.org/data/2.5/ description: Some other server

      paths — Это та же “конечная точка” в соответствии с терминологии спецификации OpenAPI. Каждый объект path содержит объект operations — это методы GET, POST, PUT, DELETE:

      paths: /weather: get:

      Объект components уникален среди других объектов в спецификации OpenAPI. В components хранятся переиспользуемые определения, которые могут появляться в нескольких местах в документе спецификации. В нашем сценарии документации API мы будем хранить детали для объектов parameters и responses в объекте components

      Conclusions

      • Документация стала более понятней для бизнес юзера так и для техническим юзерам (Swagger UI, Open Specifiation)
      • Может генерировать код для Java, PHP, .NET, JavaScrypt (Swager Editor, Swagger Codegen)
      • Можно проверять насколько совместимы изменения. Можно настраивать это в дженкинсе
      • Нет ни какой лишней документации к коде, код отдельно, документация отдельно

      Как настроить swagger

      Авторизация Swagger должна выполняться для каждого действия соединителя Swagger. В списке схем аутентификации выберите одну из схем авторизации.

      • Нет — укажите URL-адрес файла Swagger, например: https://petstore.swagger.io/v2/swagger.json
      • Базовый — чтобы добавить базовое соединение, выполните следующие действия.
      1. В списке схем аутентификации выберите Базовый .
      2. В поле Соединение Swagger щелкните Добавить новое .
      3. В окне «Добавить соединение» введите следующие сведения.
      ▪ Метка соединения — заполняется автоматически. Можно указать метку подключения по своему выбору.
      В метках учитывается регистр. Не используйте пробелы, некоторые специальные символы и ведущие цифры.
      ▪ URL Swagger — URL-адрес файла Swagger.json.
      ▪ Имя пользователя — имя пользователя для целевого приложения.
      ▪ Пароль — пароль для целевого приложения.
      4. Щелкните Добавить . Новая авторизация будет добавлена в список.
      • OAuth — чтобы добавить соединение с OAuth, выполните следующие действия.
      1. В списке схем аутентификации выберите OAuth .
      2. В поле Swagger OAuth щелкните Добавить новое имя пользователя Swagger .

      3. В окне «Параметры» введите URL-адрес Swagger , а затем щелкните РАЗРЕШИТЬ . Откроется окно «Добавить авторизацию».

      4. В окне «Добавить авторизацию» измените Метку авторизации , если необходимо, а затем введите URL-адрес ресурса.

      5. Щелкните Добавить .
      • Ключ приложения — чтобы добавить новое соединение «Ключ приложения», выполните следующие действия.
      1. В списке схем аутентификации выберите Ключ приложения .
      2. В поле Ключ приложения Swagger щелкните Добавить новый .
      3. В окне «Добавить соединение» введите следующие сведения.
      ▪ Метка соединения — заполняется автоматически. Можно указать метку подключения по своему выбору.
      В метках учитывается регистр. Не используйте пробелы, некоторые специальные символы и ведущие цифры.
      ▪ URL Swagger — URL-адрес файла Swagger.json, например: https://petstore.swagger.io/v2/swagger.json
      ▪ Ключ приложения — введите ключ приложения Swagger.
      4. Щелкните Добавить .
      Щелкните Тестировать , чтобы проверить авторизацию.
      Ограничения соединителя Swagger

      • В спецификации OpenAPI 3.0 для поля сервера существует опция определения нескольких базовых URL-адресов. Текущая реализация не поддерживает эту опцию, а из массива серверов извлекается первый базовый URL-адрес.

      • В запросе допустимы следующие типы мультимедиа: application/json and application/x-www-form-urlencoded. Подстановочные символы не разрешены. Для отклика разрешен тип application/json.

      • Выгрузка файла или изображения не поддерживается.
      • Данные multipart/form не поддерживаются.
      • Метод сериализации параметра используется по умолчанию для всех параметров.
      • Использование типов oneOf, anyOf, allOf и none в поле типа не поддерживается.

      • Множественная аутентификация не разрешена. Все интерфейсы API должны иметь одинаковую аутентификацию.

      Документирование SpringBoot API с помощью Swagger

      Веб-приложение содержит API для работы. Документирование API позволяет клиентам API быстрее понять, как использовать сервисы. Даже если API закрыт от внешнего мира, то все равно стоит уделить время спецификации — это поможет вашим новым коллегам быстрее разобраться с системой.

      6 янв. 2021 · 8 минуты на чтение

      Документирование SpringBoot API с помощью Swagger

      Создание документации вручную — утомительный процесс. В этой статье мы рассмотрим основы Swagger и его возможности по документированию REST API в SpringBoot приложении.

      Спонсор поста

      Используемые версии

      Java 17
      Spring Boot 3.0.2
      Swagger 2.2.8
      SpringDoc 1.6.14 | 2.0.2

      Изменения статьи

      29.06.22: Обновил до Java 17. Обновил все зависимости до актуальных.
      11.02.23: Обновил SpringBoot до 3.0.2. Обновил остальные зависимости. Добавил раздел с авторизацией в Swagger UI.

      Что такое Swagger?

      Swagger позволяет разработчикам описывать структуру своих API и генерировать интерактивную документацию, клиентские библиотеки и серверные модули для реализации API на разных языках.

      Swagger предоставляет спецификацию для документирования REST API, которая называется OpenAPI Specification (OAS). Эта спецификация предоставляет четкий и лаконичный способ описания эндпойнтов, их параметров, моделей запросов и ответов и других аспектов API.

      В данной статье рассматривается пример генерации OAS на основе уже существующих REST контроллеров. Мы разметим контроллеры и эндпойнты аннотациями, на основе которых будет сгенерирована OAS.

      Существуют библиотеки, которые на основе OAS могут сгенерировать интерактивную документацию для API, которая позволит отправлять запросы, и получать ответы. Мы воспользуемся библиотекой SpringDoc.

      Почему SpringDoc, а не SpringFox?

      В интернете множество статей с использованием библиотеки SpringFox для генерации Swagger UI. Почему тогда я использую какой-то SpringDoc?

      SpringFox был заброшен авторами. Последний коммит сделан в 2020 году, а количество issue уже перевалило за 200. В какой-то момент я столкнулся с каким-то багом в SpringFox, который никогда не будет исправлен, и стал искать альтернативы.

      Такой альтернативой оказался SpringDoc, который активно развивается и поддерживает SpringBoot 3. Я успешно и быстро перевел свой проект с SpringFox на SpringDoc.

      Также стоит упомянуть, что Swagger позволяет сгенерировать непосредственно код клиента или сервера по имеющейся OAS, для этого нужен генератор кода Swagger-Codegen.

      Генератором я никогда не пользовался. Генерируемый код получается весьма неказистым и проще написать его самостоятельно.

      Демо проект с REST API

      Чтобы документировать API, для начала напишем его. Вы можете перейти к следующей главе, чтобы не тратить время.

      Репозиторий с примерами: Struchkov Git | GitHub

      Добавим примитивные контроллеры и одно DTO. Бизнес суть нашей системы – программа лояльности пользователей.

      Для наших примеров достаточно слоя контроллеров, поэтому я позволю себе вольность опустить серверный и репозиторный слой и добавить бизнес логику непосредственно контроллер.

      В качестве DTO у нас будет класс UserDto – это пользователь нашей системы. У него пять полей, из которых 3 обязательны.

      UserDto.java
      public class UserDto < private String key; private String name; private Long points = 0L; private Gender gender; private LocalDateTime regDate = LocalDateTime.now(); public UserDto() < >public UserDto(String key, String name, Gender gender) < this.key = key; this.name = name; this.gender = gender; >public static UserDto of(String key, String value, Gender gender) < return new UserDto(key, value, gender); >// getters and setters >
      public enum Gender

      Для взаимодействия с нашей бизнес-логикой, добавим три контроллера: UserController , PointContoller , SecretContoller .

      UserController отвечает за добавление, обновление и получение пользователей.

      UserController.java
      @RestController @RequestMapping("/api/user") public class UserController < private final Maprepository; public UserController(Map repository) < this.repository = repository; >@PutMapping(produces = APPLICATION_JSON_VALUE) public HttpStatus registerUser(@RequestBody UserDto userDto) < repository.put(userDto.getKey(), userDto); return HttpStatus.OK; >@PostMapping(produces = APPLICATION_JSON_VALUE) public HttpStatus updateUser(@RequestBody UserDto userDto) < if (!repository.containsKey(userDto.getKey())) return HttpStatus.NOT_FOUND; repository.put(userDto.getKey(), userDto); return HttpStatus.OK; >@GetMapping(value = "", produces = APPLICATION_JSON_VALUE) public ResponseEntity getSimpleDto(@PathVariable("key") String key) < return ResponseEntity.ok(repository.get(key)); >>

      PointContoller отвечает за взаимодействие с баллами пользователя. Один метод этого контроллера отвечает за добавление и удаление балов пользователям.

      PointContoller.java
      @RestController @RequestMapping("api/user/point") public class PointController < private final Maprepository; public PointController(Map repository) < this.repository = repository; >@PostMapping("") public HttpStatus changePoints( @PathVariable String key, @RequestParam("point") Long point, @RequestParam("type") String type ) < final UserDto userDto = repository.get(key); userDto.setPoints( "plus".equalsIgnoreCase(type) ? userDto.getPoints() + point : userDto.getPoints() - point ); return HttpStatus.OK; >>

      Метод destroy в SecretContoller может удалить всех пользователей.

      SecretContoller.java
      @RestController @RequestMapping("api/secret") public class SecretController < private final Maprepository; public SecretController(Map repository) < this.repository = repository; >@GetMapping(value = "destroy") public HttpStatus destroy() < repository.clear(); return HttpStatus.OK; >>

      Настраиваем Swagger

      Ветка в репозитории: spring-boot-3

      Теперь добавим Swagger в наш проект. Для этого добавьте следующие зависимости в pom.xml :

      Swagger запущенный с дефолтными настройками

      Также можно вызвать каждый метод с помощью пользовательского интерфейса. Откроем метод добавления пользователей.

      Пока у нас не очень информативная документация. Давайте исправим это. Для начала создадим класс конфигурации сваггера OpenApiConfig — имя произвольное.

      @OpenAPIDefinition( info = @Info( title = "Loyalty System Api", description = "Loyalty System", version = "1.0.0", contact = @Contact( name = "Struchkov Mark", email = "mark@struchkov.dev", url = "https://mark.struchkov.dev" ) ) ) public class OpenApiConfig
      • title – это название вашего приложения.
      • version – версия вашего API.
      • contact – ответственные за API.

      Эти данные больше для визуальной красоты UI документации.

      Разметка контроллеров

      Переопределим описания контроллеров, чтобы сделать документацию понятнее. Для этого пометим контроллеры аннотацией @Tag .

      @Tag(name="Название контроллера", description="Описание контролера") public class ControllerName < // . . . . . >

      Добавили описание контроллеров в Swagger

      Скрыть контроллер

      У нас есть контроллер, который мы хотим скрыть – SecretController . Аннотация @Hidden поможет нам в этом.

      @Hidden @Tag(name = "Секретный контролер", description = "Позволяет удалить всех пользователей") public class SecretController < // . . . . . >

      Аннотация скрывает контроллер только из Swagger. Он все также доступен для вызова. Используйте другие методы для защиты вашего API. Например, авторизацию на основе JWT токена.

      Наша документация стала намного понятнее, но давайте добавим описания для каждого метода контроллера.

      Разметка методов

      Аннотация @Operation описывает возможности методов контроллера. Достаточно определить следующие значения:

      • summary – короткое описание.
      • description – более полное описание.
      @Operation( summary = "Регистрация пользователя", description = "Позволяет зарегистрировать пользователя" ) public HttpStatus registerUser(@RequestBody UserDto userDto) < // . . . . . >

      Разметка переменных метода

      При помощи аннотации Parameter также опишем переменные в методе, который отвечает за управление баллами пользователей.

      public HttpStatus changePoints( @PathVariable @Parameter(description = "Идентификатор пользователя") String key, @RequestParam("point") @Parameter(description = "Количество баллов") Long point, @RequestParam("type") @Parameter(description = "Тип операции") TypeOperation type ) < // . . . . . >

      С помощью параметра required можно задать обязательные поля для запроса. По умолчанию все поля необязательные.

      Разметка DTO

      Разработчики стараются называть переменные в классе понятными именами, но не всегда это помогает. Вы можете дать человеко-понятное описание самой DTO и ее переменным с помощью аннотации @Schema .

      @Schema(description = "Сущность пользователя") public class UserDto < @Schema(description = "Идентификатор") private String key; // . . . . . >

      Сваггер заполнит переменные, формат которых он понимает: enum, даты. Но если некоторые поля DTO имеют специфичный формат, то помогите разработчикам добавив пример.

      @Schema(description = "Идентификатор", example = "A-124523")

      Выглядеть это будет так:

      Но подождите, зачем мы передаем дату регистрации. Да и уникальный ключ чаще всего будет задаваться сервером. Скроем эти поля из swagger с помощью параметра Schema.AccessMode.READ_ONLY :

      public class UserDto < @Schema(accessMode = Schema.AccessMode.READ_ONLY) private String key; // . . . . . >

      Рандомный блок

      Валидация

      Про валидацию я подробно рассказывал в статье: «Валидация данных в SpringBoot». Здесь я лишь хочу показать, что валидация параметров методов контроллеров также отображается в Swagger.

      Добавим валидацию в метод управления баллами пользователя в PointController . Мы не хотим, чтобы можно было передать отрицательные баллы.

      public HttpStatus changePoints( // . . . . . @RequestParam("point") @Min(0) @Parameter(description = "Количество баллов") Long point, // . . . . . ) < // . . . . . >

      Давайте посмотрим на изменения спецификации.

      Для поля point появилось замечание minimum: 0 . И все это нам не стоило ни малейшего дополнительного усилия.

      Авторизация в Swager

      Ветка в репозитории: jwt-auth

      Если ваш API защищен авторизаций и аутентификаций, то вы не сможете просто так вызвать запрос из Swagger. Один из самых распространенных способов авторизации это JWT, о нем я рассказывал в отдельной статье.

      Сейчас нам нужно объяснить сваггеру, какая авторизация у нас применяется и какие эндпойнты ей защищены.

      Авторизация с использованием JWT

      В первом случае рассмотрим старый добрый JWT. Swagger должен получить access-токен и добавлять его в Header запросов.

      Начнем с добавления аннотации @SecurityScheme над классом OpenApiConfig :

      @OpenAPIDefinition(. ) @SecurityScheme( name = "JWT", type = SecuritySchemeType.HTTP, bearerFormat = "JWT", scheme = "bearer" ) public class OpenApiConfig

      Мы описали схему авторизации с использованием JWT. Теперь пометим аннотацией @SecurityRequirement все эндпойнты, которые используют данный способ авторизации. В @SecurityRequirement в атрибуте name указываем название нашей схемы – JWT. Название должно совпадать с названием из аннотации @SecurityScheme .

      Устанавливаем токен, после чего нажимаем кнопку Authorize. Переходим к защищенному эндпойнту и вызываем его.

      Видим, что Swagger проставил заголовок Authorization , а также сам добавил Bearer к токену. То что нам и было нужно.

      Авторизация с использованием Ouath2

      Ветка в репозитории: swagger-oauth2

      С Oauth2 все оказалось сложнее. Проблема в том, что при авторизации с использованием Oauth2 SpringBoot генерирует JSESSIONID куку, которую сохраняет в браузере. Дальше браузер передает эту куку с каждым запросом, что позволяет SpringBoot приложению понимать кто с ним общается.

      Swagger же при Oauth2 авторизации генерирует себе access token, который пытается использовать при запросе. Проблема в том, что он никак не может сам получить значение JSESSIONID , так как его генерирует Spring после успешной Oauth2 авторизации.

      Если вы знаете, как решить эту проблему, пожалуйста напишите в комментариях. Я рабочего решения быстро найти не смог.

      Поэтому для Ouath2 воспользуемся возможностью сваггера передавать куку.

      @OpenAPIDefinition(. ) @SecurityScheme( name = "jsessionid", in = SecuritySchemeIn.COOKIE, type = SecuritySchemeType.APIKEY, paramName = "JSESSIONID" ) public class OpenApiConfig

      Помечаем эндпойнты аннотацией:

      @SecurityRequirement(name = "jsessionid")

      Далее переходим по какому-нибудь урлу нашего API, видим Oauth2 окно авторизации. Проходим авторизацию. Теперь открываем консоль разработчика в браузере и находим раздел с куками.

      Вместо настоящего Oauth2 сервера можно использовать mock-server. Который принимает любой email и любой пароль. Удобно использовать при локальной разработке. Конфигурацию подключения можно посмотреть в моей заметке.

      Нас интересует кука JSESSIONID , берем ее и вставляем в окно авторизации в Swagger.

      Вот и все. Это будет работать.

      Итог

      Этих знаний вам хватит, чтобы сделать хорошее описание API вашего сервиса. Если нужны более тонкие настройки, то вы без труда сможете разобраться, открыв документацию к аннотациям сваггера.

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

      Swagger — это технология, которая позволяет документировать REST-сервисы. Swagger поддерживает множество языков программирования и фреймворков. Также Swagger предоставляет UI для просмотра документации.

      В данной статье я расскажу как подключить Swagger к Maven проекту, в котором реализованы REST-сервисы с помощью спецификации JAX-RS — RESTEasy. В статье будет расписано подключение Swagger к проекту, использование документирования REST-сервисов с помощью аннотаций, описание визуализации документации через Web UI.

      Подключение Swagger к проекту

      Подключение Maven зависимостей

      Для начала мы должны добавить в проект Maven зависимость Swagger’а. Так как мы будет подключать Swagger к RESTEasy, то добавим соответствующую зависимость.

        io.swagger swagger-jaxrs 1.5.6  

      На момент написания мануала актуальной версией является 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> getClasses() < Set> 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> getClasses() < Set> 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 ") >) 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-сервисов на UI

      Список REST сервисов на Web-UI:

      Список REST сервисов на Web-UI

      Форма детальной информации о REST-сервисе и возможности отправки запроса.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *