Рубрики
Без рубрики

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

Узнайте, как создать клиент Spring Boot REST с помощью генератора кода Swagger.

Автор оригинала: baeldung.

1. введение

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

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

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

2. Создайте Клиент REST С Помощью Swagger Codegen

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

2.1. Загрузите Файл Jar

В code-gen_cli.jar можно скачать с здесь .

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

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

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

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 , –artifact-id , –artifact-version
  • Язык программирования сгенерированного клиента – предоставляется с использованием -l
  • Структура реализации – предоставляется с использованием библиотеки –
  • Выходной каталог – предоставляется с помощью -o

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

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

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

  • jersey1 – Jersey1 + Джексон
  • jersey2 – Jersey2 + Джексон
  • притворство – OpenFeign + Джексон
  • охттп-гсон – ОХТТП + Гсон
  • retrofit (Устаревший) – Retrofit1/OkHttp + Gson
  • retrofit2 – Retrofit2/OkHttp + Gson
  • rest-шаблон – Пружинная рестемплата + Джексон
  • отдых-легко – Отдых + Джексон

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

3. Создайте Клиент REST С Помощью Генератора Открытых API

Генератор OpenAPI – это вилка кода Swagger, способная генерировать более 50 клиентов из любых документов спецификации Open API 2.0/3.x.

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

3.1. Установка

Возможно, самым простым и переносимым методом установки является использование оболочки npm package , которая работает, предоставляя оболочку 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. Создание Клиента

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

Далее, давайте сгенерируем клиент, эквивалентный тому, который мы сгенерировали с помощью 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 поддерживает все те же библиотеки Java, что и Swagger CodeGen, плюс несколько дополнительных. Следующие библиотеки Java (пары HTTP-клиентов и библиотеки обработки JSON) поддерживаются генератором Open API:

  • jersey1 – Jersey1 + Джексон
  • jersey2 – Jersey2 + Джексон
  • притворство – OpenFeign + Джексон
  • охттп-гсон – ОХТТП + Гсон
  • retrofit (Устаревший) – Retrofit1/OkHttp + Gson
  • retrofit2 – Retrofit2/OkHttp + Gson
  • опорная плита – Пружинная опорная плита + Джексон
  • webclient – Spring 5 WebClient + Jackson (только генератор OpenAPI)
  • resteasy – Resteasy + Джексон
  • vertx – VertX + Джексон
  • google-api-клиент – Клиент Google API + Джексон
  • rest-assured – rest-assured + Jackson/Gson (только Java 8)
  • native – Java native HttpClient + Jackson (только Java 11; только генератор OpenAPI)
  • микропрофиль – Клиент микропрофиля + Джексон (только генератор OpenAPI)

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

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

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

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


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

4.2. Представление классов API в виде весенних бобов

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

@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. Основное применение Пружины

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

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

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

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

@Autowired
private PetApi petApi;

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

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

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

5.1. Плагин Maven

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

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


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

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. Вы можете передать те же параметры, которые используются в CLI Swagger Codegen, чтобы настроить клиент вывода.

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

5.3. OpenAPI Generator Online Generator API

Как и Swagger Codegen, Open API 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. Вы можете передать те же параметры, которые используются в CLI Swagger Codegen, чтобы настроить клиент вывода.

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

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

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

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

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

Читайте ещё по теме: