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.