Generer Spring Boot REST Client med Swagger

1. Introduktion

I denne artikel bruger vi Swagger Codegen- og OpenAPI Generator-projekterne til at generere REST-klienter fra en OpenAPI / Swagger-spec-fil.

Vi opretter også et Spring Boot-projekt, hvor vi bruger genererede klasser.

Vi bruger eksemplet på Swagger Petstore API til alt.

2. Generer REST-klient med Swagger Codegen

Swagger leverer et værktøjskrukke, der giver os mulighed for at generere REST-klienter til forskellige programmeringssprog og flere rammer.

2.1. Download Jar-fil

Det kode-gen_cli.jar kan downloades herfra.

For den nyeste version, se venligst swagger-codegen-cli repository.

2.2. Generer klient

Lad os generere vores klient ved at udføre kommandoen java -jar swagger-code-gen-cli.jar genererer:

java -jar swagger-codegen-cli.jar genererer \ -i //petstore.swagger.io/v2/swagger.json \ --api-pakke com.baeldung.petstore.client.api \ --model-pakke com. baeldung.petstore.client.model \ --invoker-pakke com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-swagger-codegen-api-client \ --artifact -version 0.0.1-SNAPSHOT \ -l java \ --bibliotek resttemplate \ -o spring-swagger-codegen-api-client

De fremlagte argumenter består af:

  • En kilde-swagger-fil-URL eller sti - leveret ved hjælp af -jeg argument
  • Navne på pakker til genererede klasser - leveret ved hjælp af –Api-pakke, –Modelpakke, –Invoker-pakke
  • Genererede Maven-projektegenskaber –Gruppe-id, –Artifact-id, –Artifact-version
  • Programmeringssproget for den genererede klient - leveret ved hjælp af -l
  • Implementeringsrammen - leveret ved hjælp af -bibliotek
  • Outputmappen - leveres ved hjælp af -o

For at liste alle Java-relaterede indstillinger skal du skrive følgende kommando:

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

Swagger Codegen understøtter følgende Java-biblioteker (par HTTP-klienter og JSON-behandlingsbiblioteker):

  • trøje1 - Jersey1 + Jackson
  • trøje2 - Jersey2 + Jackson
  • feign - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • eftermontering (Forældet) - Eftermontering1 / OkHttp + Gson
  • eftermontering2 - Eftermontering2 / OkHttp + Gson
  • hvile-skabelon - Spring RestTemplate + Jackson
  • hvile-let - Resteasy + Jackson

I denne opskrivning valgte vi hvile-skabelon da det er en del af forårets økosystem.

3. Generer REST-klient med OpenAPI Generator

OpenAPI Generator er en gaffel af Swagger Codegen, der er i stand til at generere 50+ klienter fra alle OpenAPI Specification 2.0 / 3.x-dokumenter.

Mens Swagger Codegen vedligeholdes af SmartBear, vedligeholdes OpenAPI Generator af et samfund, der inkluderer mere end 40 af de største bidragydere og skabelonskabere af Swagger Codegen som grundlæggende teammedlemmer.

3.1. Installation

Måske er den nemmeste og mest bærbare installationsmetode at bruge npm pakkeindpakning, som fungerer ved at levere en CLI-indpakning oven på kommandolinjemulighederne understøttet af Java-koden. Installationen er ligetil:

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

For dem, der ønsker JAR-filen, kan den findes i Maven Central. Lad os downloade det nu:

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. Generer klient

For det første er mulighederne for OpenAPI Generator næsten identiske med dem for Swagger Codegen. Den mest bemærkelsesværdige forskel er udskiftning af -l sprogflag med -g generatorflag, som tager sproget for at generere klienten som en parameter.

Lad os derefter generere en klient svarende til den, vi genererede med Swagger Codegen ved hjælp af krukke kommando:

java -jar openapi-generator-cli.jar genererer \ -i //petstore.swagger.io/v2/swagger.json \ --api-pakke com.baeldung.petstore.client.api \ --model-pakke com. baeldung.petstore.client.model \ --invoker-pakke 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 = sand \ --bibliotek resttemplate \ -o fjeder-openapi-generator-api-klient

For at liste alle Java-relaterede indstillinger skal du skrive kommandoen:

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

OpenAPI Generator understøtter alle de samme Java-biblioteker som Swagger CodeGen plus et par ekstra. Følgende Java-biblioteker (par af HTTP-klienter og JSON-behandlingsbiblioteker) understøttes af OpenAPI Generator:

  • trøje1 - Jersey1 + Jackson
  • trøje2 - Jersey2 + Jackson
  • feign - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • eftermontering (Forældet) - Eftermontering1 / OkHttp + Gson
  • eftermontering2 - Eftermontering2 / OkHttp + Gson
  • resttemplate - Spring RestTemplate + Jackson
  • webklient - Spring 5 WebClient + Jackson (kun OpenAPI Generator)
  • rolig - Resteasy + Jackson
  • vertx - VertX + Jackson
  • google-api-klient - Google API-klient + Jackson
  • stol trygt på - vær sikker + Jackson / Gson (kun Java 8)
  • hjemmehørende - Java native HttpClient + Jackson (kun Java 11; kun OpenAPI Generator)
  • mikroprofil - Mikroprofilklient + Jackson (kun OpenAPI Generator)

4. Generer Spring Boot Project

Lad os nu oprette et nyt Spring Boot-projekt.

4.1. Maven afhængighed

Vi tilføjer først afhængigheden af ​​det genererede API-klientbibliotek - til vores projekt pom.xml fil:

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

4.2. Udsæt API-klasser som springbønner

For at få adgang til de genererede klasser skal vi konfigurere dem som bønner:

@Configuration public class PetStoreIntegrationConfig {@Bean public PetApi petApi () {returner ny PetApi (apiClient ()); } @Bean public ApiClient apiClient () {returner ny ApiClient (); }}

4.3. API-klientkonfiguration

Det ApiClient klasse bruges til at konfigurere godkendelse, API-basisstien, fælles overskrifter, og den er ansvarlig for at udføre alle API-anmodninger.

For eksempel, hvis du arbejder med OAuth:

@Bean offentlig ApiClient apiClient () {ApiClient apiClient = ny ApiClient (); OAuth petStoreAuth = (OAuth) apiClient.getAuthentication ("petstore_auth"); petStoreAuth.setAccessToken ("specialnøgle"); returner apiClient; }

4.4. Forårets hovedanvendelse

Vi skal importere den nyoprettede konfiguration:

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

4.5. API-brug

Da vi konfigurerede vores API-klasser som bønner, kan vi frit injicere dem i vores forårshåndterede klasser:

@Autowired privat PetApi petApi; offentlig liste findAvailablePets () {return petApi.findPetsByStatus (Arrays.asList ("tilgængelig")); }

5. Alternative løsninger

Der er andre måder at generere en REST-klient ud over at udføre Swagger Codegen eller OpenAPI Generator CLI.

5.1. Maven-plugin

Et swagger-codegen Maven-plugin, der let kan konfigureres i din pom.xml tillader generering af klienten med de samme muligheder som Swagger Codegen CLI.

Dette er et grundlæggende kodestykke, som vi kan medtage i vores projekts pom.xml at generere klient automatisk:

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

5.2. Swagger Codegen Online Generator API

En allerede offentliggjort API, der hjælper os med at generere klienten ved at sende en POST-anmodning til URL'en //generator.swagger.io/api/gen/clients/java videregivelse af specifik URL sammen med andre muligheder i anmodningens brødtekst.

Lad os lave et eksempel ved hjælp af en simpel curl-kommando:

krølle -X POST -H "indholdstype: applikation / json" \ -d '{"swaggerUrl": "// petstore.swagger.io/v2/swagger.json"}' \ //generator.swagger.io/ api / gen / klienter / java

Svaret ville være JSON-format, der indeholder et downloadbart link, der indeholder den genererede klientkode i zip-format. Du kan muligvis videregive de samme muligheder, der bruges i Swaager Codegen CLI for at tilpasse outputklienten.

//generator.swagger.io indeholder en Swagger-dokumentation til API'en, hvor vi kan kontrollere dens dokumentation og prøve den.

5.3. OpenAPI Generator Online Generator API

Ligesom Swagger Godegen har OpenAPI Generator også en online generator. Lad os udføre et eksempel ved hjælp af en simpel curl-kommando:

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

Svaret i JSON-format vil indeholde et link, der kan downloades, til den genererede klientkode i zip-format. Du kan muligvis videregive de samme muligheder, der bruges i Swagger Codegen CLI for at tilpasse outputklienten.

//github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md indeholder dokumentationen til API'en.

6. Konklusion

Swagger Codegen og OpenAPI Generator giver dig mulighed for hurtigt at generere REST-klienter til din API med mange sprog og med det valgte bibliotek. Vi kan generere klientbiblioteket ved hjælp af et CLI-værktøj, Maven-plugin eller Online API.

Dette er et Maven-baseret projekt, der indeholder tre Maven-moduler: den genererede Swagger API-klient, den genererede OpenAPI-klient og Spring Boot-applikationen.

Som altid kan du finde den tilgængelige kode på GitHub.


Populære Indlæg

Seneste indlæg

Copyright da.streamalism.org 2024
$config[zx-auto] not found$config[zx-overlay] not found