Generirajte klijenta za proljetni pokretanje REST pomoću Swaggera

1. Uvod

U ovom ćemo članku koristiti projekte Swagger Codegen i OpenAPI Generator za generiranje REST klijenata iz specifikacijske datoteke OpenAPI / Swagger.

Također, stvorit ćemo projekt Spring Boot, gdje ćemo koristiti generirane klase.

Za sve ćemo upotrijebiti primjer API-ja Swagger Petstore.

2. Generirajte REST klijenta pomoću Swagger Codegena

Swagger nudi uslužni jar koji nam omogućuje generiranje REST klijenata za razne programske jezike i više okvira.

2.1. Preuzmite datoteku Jar

The code-gen_cli.jar možete preuzeti ovdje.

Najnoviju verziju potražite u spremištu swagger-codegen-cli.

2.2. Generiraj klijenta

Generirajmo svog klijenta izvršavanjem naredbe java -jar swagger-code-gen-cli.jar generira:

java -jar swagger-codegen-cli.jar generirati \ -i //petstore.swagger.io/v2/swagger.json \ --api-package com.baeldung.petstore.client.api \ --model-package com. baeldung.petstore.client.model \ --invoker-paket com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-swagger-codegen-api-client \ --artifact -verzija 0.0.1-SNAPSHOT \ -l java \ --opremnica biblioteke \ -o spring-swagger-codegen-api-client

Navedeni argumenti sastoje se od:

  • URL ili put izvorne datoteke razmetanja - pruža se pomoću -i argument
  • Imena paketa za generirane klase - osigurana pomoću –Api-paket, –Model-paket, –Pozivnik-paket
  • Generirana svojstva projekta Maven –Grupa-id, –Artefakt-id, –Verza-artefakt
  • Programski jezik generiranog klijenta - pruža se pomoću -l
  • Implementacijski okvir - osiguran pomoću -knjižnica
  • Izlazni direktorij - pruža se pomoću -o

Da biste popisali sve opcije povezane s Java, upišite sljedeću naredbu:

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

Swagger Codegen podržava sljedeće Java knjižnice (parovi HTTP klijenata i JSON knjižnice za obradu):

  • dres1 - Jersey1 + Jackson
  • dres2 - Jersey2 + Jackson
  • hinjenje - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • naknadne ugradnje (Zastarjelo) - Retrofit1 / OkHttp + Gson
  • naknadna ugradnja2 - Retrofit2 / OkHttp + Gson
  • predložak za odmor - Spring RestTemplate + Jackson
  • mirno-lagano - Resteasy + Jackson

U ovom tekstu smo izabrali predložak za odmor jer je to dio ekosustava Proljeće.

3. Generirajte REST klijenta pomoću OpenAPI generatora

OpenAPI Generator je vilica Swagger Codegena koja može generirati 50+ klijenata iz bilo kojih OpenAPI specifikacija 2.0 / 3.x dokumenata.

Dok Swagger Codegen održava SmartBear, OpenAPI Generator održava zajednica koja uključuje više od 40 glavnih suradnika i kreatora predložaka Swagger Codegena kao članova osnivačkog tima.

3.1. Montaža

Možda najjednostavniji i najprijenosniji način instalacije je korištenje npm omot paketa, koji funkcionira pružajući CLI omot iznad opcija naredbenog retka podržanih Java kodom. Instalacija je jednostavna:

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

Za one koji žele JAR datoteku mogu je pronaći u Maven Central. Preuzmimo ga sada:

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. Generiraj klijenta

Prvo, opcije za OpenAPI Generator gotovo su identične onima za Swagger Codegen. Najznačajnija razlika je zamjena -l jezična zastava sa znakom -g zastavica generatora koja uzima jezik za generiranje klijenta kao parametar.

Dalje, generirajmo klijenta ekvivalentnog onome kojeg smo generirali sa Swagger Codegenom pomoću staklenka naredba:

java -jar openapi-generator-cli.jar generirati \ -i //petstore.swagger.io/v2/swagger.json \ --api-package com.baeldung.petstore.client.api \ --model-package com. baeldung.petstore.client.model \ --invoker-paket com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-openapi-generator-api-client \ --artifact -verzija 0.0.1-SNAPSHOT \ -g java \ -p java8 = true \ - biblioteka za odmaranje \ -o spring-openapi-generator-api-client

Da biste popisali sve opcije povezane s Javom, upišite naredbu:

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

OpenAPI Generator podržava sve iste Java knjižnice kao i Swagger CodeGen, plus nekoliko dodatnih. Sljedeće Java knjižnice (parovi HTTP klijenata i JSON knjižnice za obradu) podržavaju OpenAPI Generator:

  • dres1 - Jersey1 + Jackson
  • dres2 - Jersey2 + Jackson
  • hinjenje - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • naknadne ugradnje (Zastarjelo) - Retrofit1 / OkHttp + Gson
  • naknadna ugradnja2 - Retrofit2 / OkHttp + Gson
  • predodžba - Spring RestTemplate + Jackson
  • webclient - Spring 5 WebClient + Jackson (samo OpenAPI Generator)
  • odmoran - Resteasy + Jackson
  • vertx - VertX + Jackson
  • google-api-klijent - Google API klijent + Jackson
  • budite uvjereni - budite sigurni + Jackson / Gson (samo Java 8)
  • domorodac - Java izvorni HttpClient + Jackson (samo Java 11; samo OpenAPI Generator)
  • mikroprofil - Klijent mikroprofila + Jackson (samo OpenAPI Generator)

4. Generiraj projekt Spring Boot

Stvorimo sada novi projekt Spring Boot.

4.1. Ovisnost Mavena

Prvo ćemo dodati projekt ovisnosti biblioteke Generiranog API klijenta pom.xml datoteka:

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

4.2. Izložite API klase kao proljetni grah

Da bismo pristupili generiranim klasama, moramo ih konfigurirati kao grah:

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

4.3. Konfiguracija API klijenta

The ApiClient klasa koristi se za konfiguriranje provjere autentičnosti, osnovne staze API-ja, uobičajenih zaglavlja i odgovorna je za izvršavanje svih zahtjeva API-ja.

Na primjer, ako radite s OAuth:

@Bean public ApiClient apiClient () {ApiClient apiClient = novi ApiClient (); OAuth petStoreAuth = (OAuth) apiClient.getAuthentication ("petstore_auth"); petStoreAuth.setAccessToken ("posebni ključ"); return apiClient; }

4.4. Proljetna glavna primjena

Moramo uvesti novostvorenu konfiguraciju:

@SpringBootApplication @Import (PetStoreIntegrationConfig.class) javna klasa PetStoreApplication {public static void main (String [] args) baca izuzetak {SpringApplication.run (PetStoreApplication.class, args); }}

4.5. Upotreba API-ja

Budući da smo naše API klase konfigurirali kao grah, možemo ih slobodno ubrizgati u naše klase kojima upravlja proljeće:

@Autowired private PetApi petApi; javni popis findAvailablePets () {return petApi.findPetsByStatus (Arrays.asList ("dostupan")); }

5. Alternativna rješenja

Postoje i drugi načini generiranja REST klijenta, osim izvršavanja Swagger Codegena ili OpenAPI Generator CLI.

5.1. Dodatak Maven

Dodatak swagen-codegen Maven koji se lako može konfigurirati u vašem pom.xml omogućuje generiranje klijenta s istim opcijama kao i Swagger Codegen CLI.

Ovo je osnovni isječak koda koji možemo uključiti u projekt pom.xml za automatsko generiranje klijenta:

 io.swagger swagger-codegen-maven-plugin 2.2.3 generiranje swagger.yaml java predodžba 

5.2. API Swagger Codegen mrežnog generatora

Već objavljeni API koji nam pomaže u generiranju klijenta slanjem POST zahtjeva na URL //generator.swagger.io/api/gen/clients/java prosljeđivanje specificiranog URL-a zajedno s ostalim opcijama u tijelu zahtjeva.

Napravimo primjer pomoću jednostavne naredbe curl:

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

Odgovor bi bio JSON format koji sadrži vezu za preuzimanje koja sadrži generirani kod klijenta u zip formatu. Možete prilagoditi iste opcije korištene u Swaager Codegen CLI za prilagodbu izlaznog klijenta.

//generator.swagger.io sadrži Swagger dokumentaciju za API gdje možemo provjeriti njegovu dokumentaciju i isprobati.

5.3. API za mrežni generator OpenAPI Generator

Kao i Swagger Godegen, OpenAPI Generator također ima mrežni generator. Izvedimo primjer pomoću jednostavne naredbe curl:

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

Odgovor će u JSON formatu sadržavati vezu do generiranog klijentskog koda u zip formatu. Možete prilagoditi iste opcije korištene u Swagger Codegen CLI za prilagodbu izlaznog klijenta.

//github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md sadrži dokumentaciju za API.

6. Zaključak

Swagger Codegen i OpenAPI Generator omogućuju vam brzo generiranje REST klijenata za vaš API s više jezika i s bibliotekom po vašem izboru. Klijentsku knjižnicu možemo generirati pomoću alata CLI, dodatka Maven ili internetskog API-ja.

Ovo je projekt zasnovan na Mavenu koji sadrži tri Maven modula: generirani Swagger API klijent, generirani OpenAPI klijent i Spring Boot aplikacija.

Kao i uvijek, kôd dostupan na GitHub-u.


$config[zx-auto] not found$config[zx-overlay] not found