«1. Введение

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

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

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

2. Генерация REST-клиента с помощью Swagger Codegen

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

2.1. Скачать Jar-файл

Код-gen_cli.jar можно скачать отсюда.

Новейшую версию можно найти в репозитории swagger-codegen-cli.

2.2. Generate Client

Давайте сгенерируем наш клиент, выполнив команду 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.baeldung.petstore.client.api \
  --model-package com.baeldung.petstore.client.model \
  --invoker-package com.baeldung.petstore.client.invoker \
  --group-id com.baeldung \
  --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, — идентификатор-артефакта, — версия-артефакта Язык программирования сгенерированного клиента — предоставляется с помощью -l Среда реализации — предоставляется с помощью —библиотеки Выходной каталог — предоставляется с помощью —o

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

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

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

    jersey1 — Jersey1 + Jackson jersey2 — Jersey2 + притворство Джексона — OpenFeign + Jackson okhttp-gson — OkHttp + Gson retrofit (устаревшее) — Retrofit1/OkHttp + Gson retrofit2 — Retrofit2/OkHttp + Gso n rest-template — Spring RestTemplate + Jackson rest-easy — Resteasy + Jackson

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

3. Генерация REST-клиента с помощью OpenAPI Generator

OpenAPI Generator — это ответвление Swagger Codegen, способное генерировать более 50 клиентов из любых документов OpenAPI Specification 2.0/3.x.

В то время как Swagger Codegen поддерживается SmartBear, OpenAPI Generator поддерживается сообществом, в которое входят более 40 ведущих участников и создателей шаблонов Swagger Codegen в качестве членов команды-основателя.

3.1. Установка

Возможно, самый простой и переносимый метод установки — использование оболочки пакета npm, которая работает, предоставляя оболочку CLI поверх параметров командной строки, поддерживаемых кодом Java. Установка проста: 

npm install @openapitools/openapi-generator-cli -g

Если вам нужен файл JAR, его можно найти в Maven Central. Давайте загрузим его сейчас: 

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.2.3/openapi-generator-cli-4.2.3.jar \
  -O openapi-generator-cli.jar

3.2. Generate Client

Во-первых, параметры OpenAPI Generator почти идентичны параметрам Swagger Codegen. Наиболее заметным отличием является замена флага языка -l на флаг генератора -g, который использует язык для генерации клиента в качестве параметра.

Далее давайте создадим клиент, эквивалентный тому, который мы создали с помощью Swagger Codegen, используя команду jar: 

java -jar openapi-generator-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-package com.baeldung.petstore.client.api \
  --model-package com.baeldung.petstore.client.model \
  --invoker-package com.baeldung.petstore.client.invoker \
  --group-id com.baeldung \
  --artifact-id spring-openapi-generator-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -g java \
  -p java8=true \
  --library resttemplate \
  -o spring-openapi-generator-api-client

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

java -jar openapi-generator-cli.jar config-help -g java

OpenAPI Generator supports все те же библиотеки Java, что и Swagger CodeGen, плюс несколько дополнительных. Генератор OpenAPI поддерживает следующие библиотеки Java (пары HTTP-клиентов и библиотек обработки JSON):

    jersey1 — Jersey1 + Jackson jersey2 — Jersey2 + Jackson feign — OpenFeign + Jackson okhttp-gson — OkHttp + Gson retrofit (устаревшее) — Retrofit1/OkHttp + Gson retrofit2 — Retrofit2/OkHttp + Gson resttemplate — Spring RestTemplate + веб-клиент Jackson — Spring 5 WebClient + Jackson (только OpenAPI Generator) resteasy — Resteasy + Jackson vertx — VertX + Jackson google-api-client — клиент Google API + Jackson rest-assured — rest-assured + Jackson/Gson (только для Java 8) native — Java native HttpClient + Jackson (только для Java 11; только для генератора OpenAPI) microprofile — клиент микропрофиля + Jackson (только для генератора OpenAPI)

4. Создание проекта Spring Boot

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

4.1. Зависимость Maven

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

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>spring-swagger-codegen-api-client</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

4.2. Предоставление API-классов как Spring Beans

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

@Configuration
public class PetStoreIntegrationConfig {

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

4.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;
}

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

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

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

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

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

@Autowired
private PetApi petApi;

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

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

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

5.1. Плагин Maven

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

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

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.2.3</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>swagger.yaml</inputSpec>
                <language>java</language>
                <library>resttemplate</library>
            </configuration>
        </execution>
    </executions>
</plugin>

5.2. Swagger Codegen Online Generator API

Уже опубликованный API, который помогает нам генерировать клиент, отправляя запрос POST на URL-адрес http://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. Вы можете передать те же параметры, что и в интерфейсе командной строки Swager Codegen, для настройки выходного клиента.

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

5.3. OpenAPI Generator Online Generator API

Как и Swagger Godegen, OpenAPI Generator также имеет онлайн-генератор. Давайте выполним пример с помощью простой команды curl: 

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

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

https://github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md содержит документацию по API.

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

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

Это проект на основе Maven, который содержит три модуля Maven: сгенерированный клиент Swagger API, сгенерированный клиент OpenAPI и приложение Spring Boot.

Как всегда, вы можете найти код на GitHub.