Swagger

это инструментарий, использующий спецификацию OpenAPI

Swagger — это инструментарий, использующий спецификацию OpenAPI. Например, OpenAPIGenerator и SwaggerUI. Спецификация OpenAPI (openapi.json). Спецификация OpenAPI — это документ, описывающий возможности API. Документ основан на XML и заметках атрибутов в контроллерах и моделях. Это основная часть потока OpenAPI, которая используется для управления такими инструментами, как SwaggerUI. По умолчанию он называется openapi.json. OpenAPI – открытый формат описания HTTP API, не завязанный на какую-то конкретную экосистему. Он позволяет обмениваться точным описанием API между системами, которые в иных условиях требовали бы ручной "синхронизации" API. Есть большое количество инструментов, работающих на базе OpenAPI спецификаций. Хорошим ресурсом таких проектов является openapi.tools. Открытый API (часто называемый публичным API) - это общедоступный интерфейс прикладного программирования, который предоставляет разработчикам программный доступ к проприетарному программному приложению или веб-сервису. API-интерфейсы-это наборы требований, которые определяют, как одно приложение может взаимодействовать и взаимодействовать с другим.

Теперь поговорим об Swagger

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

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

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

Swagger Tools

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

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

Swagger Core

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

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

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

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

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.1.6</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.2</version>
</dependency>

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

<plugin>
 <groupId>org.springdoc</groupId>
 <artifactId>springdoc-openapi-maven-plugin</artifactId>
 <version>0.3</version>
 <executions>
   <execution>
   <phase>integration-test</phase>
   <goals>
     <goal>generate</goal>
   </goals>
   </execution>
 </executions>
 <configuration>
   <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
   <outputFileName>openapi.yaml</outputFileName>
   <outputDir>${project.build.directory}</outputDir>
 </configuration>
</plugin>

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

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

@Bean
public OpenAPI customOpenApi(@Value("${application-description}")String appDescription,
                             @Value("${application-version}")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<UserApi> 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
Server stub:
- Kotlin
- C# (ASP.NET Core, NancyFx)
- C++ (Pistache, Restbed)
- Haskell (Servant)
- Python (Flask)
- NodeJS
- Ruby (Sinatra, Rails5)
- Rust (rust-server)
API documentation generators:
- HTML
- Confluence Wiki
Other:
- JMeter

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

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.18</version>
</dependency>

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

code<dependency>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.24</version>
</dependency>

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

// Some code   <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>3.3.4</version>
        <executions>
          <execution>
            <phase>compile</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <generatorName>spring</generatorName>
              <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
              <output>${project.build.directory}/generated-sources</output>
              <apiPackage>com.api</apiPackage>
              <modelPackage>com.model</modelPackage>
              <supportingFilesToGenerate>
                ApiUtil.java
              </supportingFilesToGenerate>
              <configOptions>
                <groupId>${project.groupId}</groupId>
                <artifactId>${project.artifactId}</artifactId>
                <artifactVersion>${project.version}</artifactVersion>
                <delegatePattern>true</delegatePattern>
                <sourceFolder>swagger</sourceFolder>
                <library>spring-mvc</library>
                <interfaceOnly>true</interfaceOnly>
                <useBeanValidation>true</useBeanValidation>
                <dateLibrary>java8</dateLibrary>
                <java8>true</java8>
              </configOptions>
              <ignoreFileOverride>${project.basedir}/.openapi-generator-ignore</ignoreFileOverride>
            </configuration>
          </execution>
        </executions>
      </plugin>

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

Запустив джарник 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

PreviousЛогирование (Logs)NextPostman

Last updated 1 year ago