Перейти к основному содержимому

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

· 7 мин. чтения

1. Введение​

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

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

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

2. Создайте клиент REST с помощью Swagger Codegen​

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

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

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

Для получения последней версии проверьте репозиторий 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.foreach.petstore.client.api \
  --model-package com.foreach.petstore.client.model \
  --invoker-package com.foreach.petstore.client.invoker \
  --group-id com.foreach \
  --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):

  • Джерси1 – Джерси1 + Джексон
  • Джерси2 – Джерси2 + Джексон
  • притворяться – OpenFeign + Джексон
  • okhttp-gson — OkHttp + Gson
  • дооснащение (устарело) – Retrofit1/OkHttp + Gson
  • retrofit2 – Retrofit2/OkHttp + Gson
  • шаблон отдыха — Spring RestTemplate + Джексон
  • отдых-легко – Resteasy + Джексон

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

3. Сгенерируйте REST-клиент с помощью генератора OpenAPI​

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. Создать клиента​

Во-первых, параметры 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.foreach.petstore.client.api \
  --model-package com.foreach.petstore.client.model \
  --invoker-package com.foreach.petstore.client.invoker \
  --group-id com.foreach \
  --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, а также несколько дополнительных. Генератор OpenAPI поддерживает следующие библиотеки Java (пары HTTP-клиентов и библиотек обработки JSON):

  • Джерси1 – Джерси1 + Джексон
  • Джерси2 – Джерси2 + Джексон
  • притворяться – OpenFeign + Джексон
  • okhttp-gson — OkHttp + Gson
  • дооснащение (устарело) – Retrofit1/OkHttp + Gson
  • retrofit2 – Retrofit2/OkHttp + Gson
  • resttemplate — Spring RestTemplate + Джексон
  • веб-клиент — Spring 5 WebClient + Jackson (только генератор OpenAPI)
  • отдых – отдых + Джексон
  • верткс — VertX + Джексон
  • google-api-client — Клиент Google API + Джексон
  • `спокойный — спокойный + Джексон/Гсон (только для Java 8 )`
  • native — собственный Java HttpClient + Jackson (только для Java 11; только для генератора OpenAPI)
  • microprofile — клиент микропрофиля + Джексон (только генератор OpenAPI)

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

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

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

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

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

4.2. Выставляйте классы API как Spring Bean-компоненты​

Чтобы получить доступ к сгенерированным классам, нам нужно настроить их как 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 или интерфейса командной строки OpenAPI Generator.

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. API-интерфейс онлайн-генератора Swagger Codegen​

Уже опубликованный 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 Онлайн генератор 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 .