Jana Pelanggan REST Spring Boot dengan Swagger

1. Pengenalan

Dalam artikel ini, kami akan menggunakan projek Swagger Codegen dan OpenAPI Generator untuk menghasilkan klien REST dari fail spesifikasi OpenAPI / Swagger.

Juga, kami akan membuat projek Spring Boot, di mana kami akan menggunakan kelas yang dihasilkan.

Kami akan menggunakan contoh Swagger Petstore API untuk semuanya.

2. Jana Pelanggan REST Dengan Swagger Codegen

Swagger menyediakan balang utiliti yang membolehkan kami menghasilkan klien REST untuk pelbagai bahasa pengaturcaraan dan pelbagai kerangka.

2.1. Muat turun Fail Jar

The kod gen_cli.jar boleh dimuat turun dari sini.

Untuk versi terbaru, sila periksa repositori swagger-codegen-cli.

2.2. Jana Pelanggan

Mari buat pelanggan kami dengan melaksanakan arahan java -jar swagger-code-gen-cli.jar menghasilkan:

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

Argumen yang disediakan terdiri daripada:

  • URL atau jalur fail swagger sumber - disediakan menggunakan argumen -i
  • Nama pakej untuk kelas yang dihasilkan - disediakan menggunakan –api-package , –model-package , –invoker-package
  • Menghasilkan sifat projek Maven –group-id , –artifact-id , –artifact-version
  • Bahasa pengaturcaraan klien yang dihasilkan - disediakan menggunakan -l
  • Kerangka pelaksanaan - disediakan menggunakan –pustaka
  • Direktori output - disediakan menggunakan -o

Untuk menyenaraikan semua pilihan yang berkaitan dengan Java, ketik perintah berikut:

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

Swagger Codegen menyokong perpustakaan Java berikut (pasangan klien HTTP dan perpustakaan pemprosesan JSON):

  • jersi1 - Jersi1 + Jackson
  • jersi2 - Jersey2 + Jackson
  • pura-pura - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • retrofit (Usang) - Retrofit1 / OkHttp + Gson
  • retrofit2 - Retrofit2 / OkHttp + Gson
  • rest-template - Spring RestTemplate + Jackson
  • rehat-senang - Rehat + Jackson

Dalam penulisan ini, kami memilih templat rehat kerana ia merupakan sebahagian daripada ekosistem Spring.

3. Jana Pelanggan REST Dengan OpenAPI Generator

OpenAPI Generator adalah garpu Swagger Codegen yang mampu menghasilkan 50+ pelanggan dari sebarang dokumen OpenAPI Specification 2.0 / 3.x.

Walaupun Swagger Codegen dikendalikan oleh SmartBear, OpenAPI Generator dikendalikan oleh komuniti yang merangkumi lebih dari 40 penyumbang teratas dan pencipta templat Swagger Codegen sebagai ahli pasukan pengasas.

3.1. Pemasangan

Mungkin kaedah pemasangan yang paling mudah dan mudah alih adalah menggunakan pembungkus paket npm , yang berfungsi dengan menyediakan pembungkus CLI di atas pilihan baris perintah yang disokong oleh kod Java. Pemasangan adalah mudah:

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

Bagi mereka yang menginginkan fail JAR, ia boleh didapati di Maven Central. Mari muat turun sekarang:

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. Jana Pelanggan

Pertama, pilihan untuk OpenAPI Generator hampir sama dengan pilihan untuk Swagger Codegen. Perbezaan yang paling ketara ialah penggantian bendera bahasa -l dengan bendera penjana -g , yang mengambil bahasa untuk menghasilkan klien sebagai parameter.

Seterusnya, mari buat pelanggan yang setara dengan yang kami hasilkan dengan Swagger Codegen menggunakan perintah 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

Untuk menyenaraikan semua pilihan yang berkaitan dengan Java, ketik perintah:

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

OpenAPI Generator menyokong semua perpustakaan Java yang sama dengan Swagger CodeGen ditambah beberapa tambahan. Perpustakaan Java berikut (pasangan klien HTTP dan perpustakaan pemprosesan JSON) disokong oleh OpenAPI Generator:

  • jersi1 - Jersi1 + Jackson
  • jersi2 - Jersey2 + Jackson
  • pura-pura - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • retrofit (Usang) - Retrofit1 / OkHttp + Gson
  • retrofit2 - Retrofit2 / OkHttp + Gson
  • resttemplate - Spring RestTemplate + Jackson
  • pelanggan web - Spring 5 WebClient + Jackson (OpenAPI Generator sahaja)
  • rehat - Resteasy + Jackson
  • vertx - VertX + Jackson
  • google-api-client - Google API Client + Jackson
  • yakinlah - yakinlah + Jackson / Gson (Java 8 sahaja)
  • asli - Java asli HttpClient + Jackson (Java 11 sahaja; OpenAPI Generator sahaja)
  • microprofile - Pelanggan microprofile + Jackson (OpenAPI Generator sahaja)

4. Hasilkan Projek Spring Boot

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 dan OpenAPI Generator membolehkan anda menjana klien REST dengan cepat untuk API anda dengan banyak bahasa dan dengan perpustakaan pilihan anda. Kami dapat menjana perpustakaan pelanggan menggunakan alat CLI, plugin Maven, atau API Dalam Talian.

Ini adalah projek berbasis Maven yang berisi tiga modul Maven: klien Swagger API yang dihasilkan, klien OpenAPI yang dihasilkan, dan aplikasi Spring Boot.

Seperti biasa, anda boleh mendapatkan kod yang terdapat di GitHub.