streamalism.org

1. Introduksjon

I denne artikkelen bruker vi Swagger Codegen- og OpenAPI Generator-prosjektene til å generere REST-klienter fra en OpenAPI / Swagger-spesifikasjonsfil.

Vi oppretter også et Spring Boot-prosjekt der vi bruker genererte klasser.

Vi bruker Swagger Petstore API-eksemplet for alt.

2. Generer REST-klient med Swagger Codegen

Swagger gir en verktøykrukke som lar oss generere REST-klienter for forskjellige programmeringsspråk og flere rammer.

2.1. Last ned Jar-fil

De code-gen_cli.jar kan lastes ned herfra.

For den nyeste versjonen kan du sjekke repositoriet swagger-codegen-cli.

2.2. Generer klient

La oss generere klienten vår ved å utføre kommandoen java -jar swagger-code-gen-cli.jar generere:

java -jar swagger-codegen-cli.jar genererer \ -i //petstore.swagger.io/v2/swagger.json \ --api-pakke com.baeldung.petstore.client.api \ --modell-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 -versjon 0.0.1-SNAPSHOT \ -l java \ - bibliotek resttemplate \ -o spring-swagger-codegen-api-client

De angitte argumentene består av:

• En kilde-swagger-fil-URL eller -bane - oppgitt ved hjelp av -Jeg argument
• Navn på pakker for genererte klasser - oppgitt ved hjelp av –Api-pakke, –Modell-pakke, –Invoker-pakke
• Genererte Maven-prosjektegenskaper –Gruppe-id, –Artifact-id, –Artifact-versjon
• Programmeringsspråket til den genererte klienten - levert med -l
• Implementeringsrammeverket - gitt ved hjelp av -bibliotek
• Utdatakatalogen - levert ved hjelp av -o

For å liste alle Java-relaterte alternativer, skriv inn følgende kommando:

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

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

• jersey1 - Jersey1 + Jackson
• jersey2 - Jersey2 + Jackson
• late som - OpenFeign + Jackson
• okhttp-gson - OkHttp + Gson
• ettermontere (Foreldet) - ettermontering1 / OkHttp + Gson
• ettermontering2 - Ettermontering2 / OkHttp + Gson
• hvilemal - Spring RestTemplate + Jackson
• slapp av - Resteasy + Jackson

I denne oppskriften valgte vi hvilemal som det er en del av vårens økosystem.

3. Generer REST-klient med OpenAPI Generator

OpenAPI Generator er en gaffel av Swagger Codegen som kan generere 50+ klienter fra alle OpenAPI Specification 2.0 / 3.x-dokumenter.

Mens Swagger Codegen vedlikeholdes av SmartBear, vedlikeholdes OpenAPI Generator av et samfunn som inkluderer mer enn 40 av de beste bidragsyterne og malskaperne til Swagger Codegen som grunnleggende teammedlemmer.

3.1. Installasjon

Kanskje den enkleste og mest bærbare installasjonsmetoden er å bruke npm pakkeinnpakning, som fungerer ved å tilby en CLI-innpakning oppå kommandolinjealternativene som støttes av Java-koden. Installasjonen er grei:

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

For de som ønsker JAR-filen, finner du den i Maven Central. La oss laste den ned nå:

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 alternativene for OpenAPI Generator nesten identiske med de for Swagger Codegen. Den mest bemerkelsesverdige forskjellen er erstatning av -l språkflagg med -g generatorflagg, som tar språket for å generere klienten som parameter.

Deretter la oss generere en klient som tilsvarer den vi genererte med Swagger Codegen ved hjelp av krukke kommando:

java -jar openapi-generator-cli.jar genererer \ -i //petstore.swagger.io/v2/swagger.json \ --api-pakke com.baeldung.petstore.client.api \ --modell-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 -versjon 0.0.1-SNAPSHOT \ -g java \ -p java8 = true \ --bibliotek resttemplate \ -o spring-openapi-generator-api-client

For å liste alle Java-relaterte alternativer, skriv inn kommandoen:

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

OpenAPI Generator støtter alle de samme Java-bibliotekene som Swagger CodeGen pluss noen få ekstra. Følgende Java-biblioteker (par HTTP-klienter og JSON-behandlingsbiblioteker) støttes av OpenAPI Generator:

• jersey1 - Jersey1 + Jackson
• jersey2 - Jersey2 + Jackson
• late som - OpenFeign + Jackson
• okhttp-gson - OkHttp + Gson
• ettermontere (Foreldet) - ettermontering1 / OkHttp + Gson
• ettermontering2 - Ettermontering2 / OkHttp + Gson
• resttemplate - Spring RestTemplate + Jackson
• nettklient - Spring 5 WebClient + Jackson (kun OpenAPI Generator)
• slapp av - Resteasy + Jackson
• vertx - VertX + Jackson
• google-api-klient - Google API Client + Jackson
• være trygg - trygg + Jackson / Gson (bare Java 8)
• innfødt - Java native HttpClient + Jackson (bare Java 11; kun OpenAPI Generator)
• mikroprofil - Mikroprofilklient + Jackson (kun OpenAPI Generator)

4. Generer Spring Boot Project

La oss nå lage et nytt Spring Boot-prosjekt.

4.1. Maven avhengighet

Vi legger først til avhengigheten av det genererte API-klientbiblioteket - til prosjektet vårt pom.xml fil:

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

4.2. Utsett API-klasser som vårbønner

For å få tilgang til de genererte klassene, må vi konfigurere dem som bønner:

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

4.3. API-klientkonfigurasjon

De ApiClient klasse brukes til å konfigurere autentisering, grunnstien til API-en, vanlige overskrifter, og den er ansvarlig for å utføre alle API-forespørsler.

Hvis du for eksempel jobber med OAuth:

@Bean public ApiClient apiClient () {ApiClient apiClient = new ApiClient (); OAuth petStoreAuth = (OAuth) apiClient.getAuthentication ("petstore_auth"); petStoreAuth.setAccessToken ("spesialnøkkel"); retur apiClient; }

4.4. Vårens hovedapplikasjon

Vi må importere den nyopprettede konfigurasjonen:

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

4.5. API-bruk

Siden vi konfigurerte API-klassene våre som bønner, kan vi fritt injisere dem i våre vårstyrte klasser:

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

5. Alternative løsninger

Det er andre måter å generere en REST-klient på, annet enn å utføre Swagger Codegen eller OpenAPI Generator CLI.

5.1. Maven Plugin

Et swagger-codegen Maven-plugin som enkelt kan konfigureres i din pom.xml tillater å generere klienten med de samme alternativene som Swagger Codegen CLI.

Dette er en grunnleggende kodebit som vi kan inkludere i prosjektet vårt pom.xml å generere klient automatisk:

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

5.2. Swagger Codegen Online Generator API

Et allerede publisert API som hjelper oss med å generere klienten ved å sende en POST-forespørsel til URL-en //generator.swagger.io/api/gen/clients/java overføring av spesifikke URL-er sammen med andre alternativer i forespørselsteksten.

La oss gjøre et eksempel ved hjelp av en enkel krøllkommando:

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

Svaret vil være JSON-format som inneholder en nedlastbar lenke som inneholder den genererte klientkoden i zip-format. Du kan passere de samme alternativene som brukes i Swaager Codegen CLI for å tilpasse utdataklienten.

//generator.swagger.io inneholder en Swagger-dokumentasjon for API-et der vi kan sjekke dokumentasjonen og prøve den.

5.3. OpenAPI Generator Online Generator API

I likhet med Swagger Godegen har OpenAPI Generator også en online generator. La oss utføre et eksempel ved hjelp av en enkel krøllkommando:

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 inneholde en nedlastbar lenke til den genererte klientkoden i zip-format. Du kan passere de samme alternativene som brukes i Swagger Codegen CLI for å tilpasse utdataklienten.

//github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md inneholder dokumentasjonen for API.

6. Konklusjon

Swagger Codegen og OpenAPI Generator lar deg generere REST-klienter raskt for API-en din med mange språk og med det valgte biblioteket. Vi kan generere klientbiblioteket ved hjelp av et CLI-verktøy, Maven-plugin eller Online API.

Dette er et Maven-basert prosjekt som inneholder tre Maven-moduler: den genererte Swagger API-klienten, den genererte OpenAPI-klienten og Spring Boot-applikasjonen.

Som alltid kan du finne koden tilgjengelig på GitHub.