Создать REST-клиент Spring Boot с помощью Swagger

1. Вступление

В этой статье мы будем использовать проектSwagger CodeGen для создания клиента REST из файлаOpenAPI/Swagger spec.

Также мы создадим проект Spring Boot, в котором будем использовать сгенерированные классы.

Мы будем использовать пример APISwagger Petstore для всего.

2. Создать клиент REST

Swagger предоставляет утилиту jar, которая позволяет нам генерировать REST-клиенты для различных языков программирования и различных сред.

2.1. Загрузить файл Jar

code-gen_cli.jar можно загрузить сhere.

Для получения последней версии проверьте репозиторийswagger-codegen-cli.

2.2. Создать клиента

Давайте сгенерируем нашего клиента, выполнив командуjava -jar swagger-code-gen-cli.jar generate:

java -jar swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-package com.example.petstore.client.api \
  --model-package com.example.petstore.client.model \
  --invoker-package com.example.petstore.client.invoker \
  --group-id com.example \
  --artifact-id spring-swagger-codegen-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -l java \
  --library resttemplate \
  -o spring-swagger-codegen-api-client

Предоставленные аргументы состоят из:

URL-адрес или путь к исходному файлу swagger - предоставляется с использованием аргумента-i
Имена пакетов для сгенерированных классов - предоставляются с использованием–api-package,–model-package,–invoker-package
Сгенерированные свойства проекта Maven–group-id,–artifact-id,–artifact-version
Язык программирования сгенерированного клиента - предоставляется с использованием-l
Структура реализации - предоставляется с использованием–library
Выходной каталог - предоставляется с использованием-o

Чтобы получить список всех параметров, связанных с Java, введите следующую команду:

java -jar swagger-codegen-cli.jar config-help -l java

Swagger Codegen поддерживает следующие библиотеки Java (пары HTTP-клиентов и библиотеки обработки JSON):

jersey1 - Джерси1 + Джексон
jersey2 - Джерси2 + Джексон
feign - OpenFeign + Джексон
okhttp-gson - OkHttp + Gson
retrofit (Устарело) - Retrofit1 / OkHttp + Gson
retrofit2 - Retrofit2 / OkHttp + Gson
rest-template - Spring RestTemplate + Jackson
rest-easy - Рестизи + Джексон

В этой статье мы выбралиrest-template, поскольку он является частью экосистемы Spring.

3. Создать проект загрузки Spring

Теперь давайте создадим новый проект Spring Boot.

3.1. Maven Dependency

Сначала мы добавим зависимость клиентской библиотеки Generated API в файл нашего проектаpom.xml:


    com.example
    spring-swagger-codegen-api-client
    0.0.1-SNAPSHOT

3.2. Предоставление классов API как компонентов Spring

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

@Configuration
public class PetStoreIntegrationConfig {

    @Bean
    public PetApi petApi() {
        return new PetApi(apiClient());
    }

    @Bean
    public ApiClient apiClient() {
        return new ApiClient();
    }
}

3.3. Конфигурация клиента API

КлассApiClient используется для настройки аутентификации, базового пути API, общих заголовков и отвечает за выполнение всех запросов API.

Например, если вы работаете с OAuth:

@Bean
public ApiClient apiClient() {
    ApiClient apiClient = new ApiClient();

    OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth");
    petStoreAuth.setAccessToken("special-key");

    return apiClient;
}

3.4. Основное приложение Spring

Нам нужно импортировать вновь созданную конфигурацию:

@SpringBootApplication
@Import(PetStoreIntegrationConfig.class)
public class PetStoreApplication {
    public static void main(String[] args) throws Exception {
        SpringApplication.run(PetStoreApplication.class, args);
    }
}

3.5. Использование API

Поскольку мы настроили наши API-классы как бины, мы можем свободно внедрять их в наши классы, управляемые Spring:

@Autowired
private PetApi petApi;

public List findAvailablePets() {
    return petApi.findPetsByStatus(Arrays.asList("available"));
}

4. Альтернативные решения

Существуют и другие способы генерации REST-клиента, отличные от выполнения Swagger Codegen CLI.

4.1. Maven Plugin

swagger-codegen Maven plugin, который можно легко настроить вpom.xml, позволяет сгенерировать клиента с теми же параметрами, что и интерфейс командной строки Swagger Codegen.

Это базовый фрагмент кода, который мы можем включить вpom.xml нашего проекта для автоматического создания клиента:


    io.swagger
    swagger-codegen-maven-plugin
    2.2.3
    
        
            
                generate
            
            
                swagger.yaml
                java
                resttemplate

4.2. API онлайн-генератора

Уже опубликованный API, который помогает нам сгенерировать клиента, отправив запрос POST на URLhttp://generator.swagger.io/api/gen/clients/java, передав URL-адрес спецификации вместе с другими параметрами в теле запроса.

Давайте рассмотрим пример с помощью простой команды curl:

curl -X POST -H "content-type:application/json" \
-d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' \
http://generator.swagger.io/api/gen/clients/java

Ответ будет в формате JSON, который содержит загружаемую ссылку, которая содержит сгенерированный код клиента в формате zip. Вы можете передать те же параметры, которые использовались в Swaager Codegen CLI для настройки клиента вывода.

https://generator.swagger.io содержит документацию Swagger для API, где мы можем проверить его документацию и попробовать.

5. Заключение

Swagger Codegen позволяет вам быстро создавать REST-клиенты для вашего API со многими языками и с библиотекой по вашему выбору. Мы можем сгенерировать клиентскую библиотеку, используя инструмент CLI, плагин Maven или Online API.

Реализацию этого примера можно найти в этомGitHub project. Это проект на основе Maven, который содержит два модуля Maven, сгенерированный клиент API и приложение Spring Boot.

TOC

Создать REST-клиент Spring Boot с помощью Swagger