Генерирайте REST клиент на Spring Boot с Swagger

1. Въведение

В тази статия ще използваме проектите на Swagger Codegen и OpenAPI Generator, за да генерираме REST клиенти от спецификационен файл OpenAPI / Swagger.

Също така ще създадем проект Spring Boot, където ще използваме генерирани класове.

За всичко ще използваме примера на API на Swagger Petstore.

2. Генерирайте REST клиент с Swagger Codegen

Swagger предоставя полезност, която ни позволява да генерираме 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 //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 адрес или път на файл за преместване на източник - предоставен с помощта на аргумента -i
  • Имена на пакети за генерирани класове - предоставени с помощта на –api-package , –model-package , –invoker-package
  • Генериран Maven свойства проекта -група-ID , -artifact-ID , -artifact-версия
  • Езикът за програмиране на генерирания клиент - предоставен с помощта на -l
  • Рамката за изпълнение - предоставена с помощта на –библиотеката
  • Изходната директория - предоставена с помощта на -o

За да изброите всички опции, свързани с Java, въведете следната команда:

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

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

  • jersey1 - Jersey1 + Jackson
  • jersey2 - Jersey2 + Jackson
  • преструвам - OpenFeign + Джексън
  • okhttp-gson - OkHttp + Gson
  • модернизация (остаряла) - модернизация1 / OkHttp + Gson
  • retrofit2 - Retrofit2 / OkHttp + Gson
  • rest-template - Spring RestTemplate + Jackson
  • спокойно - Resteasy + Jackson

В това описание ние избрахме шаблон за почивка, тъй като той е част от пролетната екосистема.

3. Генерирайте REST клиент с OpenAPI генератор

OpenAPI Generator е вилица на Swagger Codegen, способна да генерира 50+ клиенти от всякакви OpenAPI спецификации 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 //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 //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 поддържа всички същите Java библиотеки като Swagger CodeGen плюс няколко допълнителни. Следните Java библиотеки (двойки HTTP клиенти и JSON обработващи библиотеки) се поддържат от OpenAPI Generator:

  • jersey1 - Jersey1 + Jackson
  • jersey2 - Jersey2 + Jackson
  • преструвам - OpenFeign + Джексън
  • okhttp-gson - OkHttp + Gson
  • модернизация (остаряла) - модернизация1 / OkHttp + Gson
  • retrofit2 - Retrofit2 / OkHttp + Gson
  • resttemplate - Spring RestTemplate + Jackson
  • webclient - Spring 5 WebClient + Jackson (само OpenAPI генератор)
  • resteasy - Resteasy + Jackson
  • vertx - VertX + Джаксън
  • google-api-client - Google API Client + Jackson
  • спокойни - спокойни + Jackson / Gson (само Java 8)
  • native - Java native HttpClient + Jackson (само Java 11; само OpenAPI генератор)
  • микропрофил - клиент на микропрофил + Джаксън (само OpenAPI генератор)

4. Генериране на проект за пролетно стартиране

Let's now create a new Spring Boot project.

4.1. Maven Dependency

We'll first add the dependency of the Generated API Client library – to our project pom.xml file:

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

4.2. Expose API Classes as Spring Beans

To access the generated classes, we need to configure them as beans:

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

4.3. API Client Configuration

The ApiClient class is used for configuring authentication, the base path of the API, common headers, and it's responsible for executing all API requests.

For example, if you're working with 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 Main Application

We need to import the newly created configuration:

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

4.5. API Usage

Since we configured our API classes as beans, we can freely inject them in our Spring-managed classes:

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

5. Alternative Solutions

There are other ways of generating a REST client other than executing Swagger Codegen or OpenAPI Generator CLI.

5.1. Maven Plugin

A swagger-codegen Maven plugin that can be configured easily in your pom.xml allows generating the client with the same options as Swagger Codegen CLI.

This is a basic code snippet that we can include in our project's pom.xml to generate client automatically:

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

5.2. Swagger Codegen Online Generator API

An already published API that helps us with generating the client by sending a POST request to the URL //generator.swagger.io/api/gen/clients/java passing the spec URL alongside with other options in the request body.

Let's do an example using a simple curl command:

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

The response would be JSON format that contains a downloadable link that contains the generated client code in zip format. You may pass the same options used in the Swaager Codegen CLI to customize the output client.

//generator.swagger.io contains a Swagger documentation for the API where we can check its documentation and try it.

5.3. OpenAPI Generator Online Generator API

Like Swagger Godegen, OpenAPI Generator also has an online generator. Let's perform an example using a simple curl command:

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

The response, in JSON format, will contain a downloadable link to the generated client code in zip format. You may pass the same options used in the Swagger Codegen CLI to customize the output client.

//github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md contains the documentation for the API.

6. Conclusion

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

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

Както винаги, можете да намерите кода, наличен в GitHub.