streamalism.org

1. Úvod

V tomto článku použijeme na generovanie klientov REST zo súboru spec OpenAPI / Swagger projekty Swagger Codegen a OpenAPI Generator.

Taktiež vytvoríme projekt Spring Boot, kde použijeme vygenerované triedy.

Na všetko použijeme príklad Swagger Petstore API.

2. Vytvorte klienta REST pomocou aplikácie Swagger Codegen

Swagger poskytuje nástrojovú nádobu, ktorá nám umožňuje generovať klientov REST pre rôzne programovacie jazyky a viac rámcov.

2.1. Stiahnite si súbor Jar

The code-gen_cli.jar je možné stiahnuť tu.

Najnovšiu verziu nájdete v úložisku swagger-codegen-cli.

2.2. Generovať klienta

Poďme vygenerovať nášho klienta vykonaním príkazu java -jar swagger-code-gen-cli.jar generovať:

java -jar swagger-codegen-cli.jar generovať \ -i //petstore.swagger.io/v2/swagger.json \ --api-balíček com.baeldung.petstore.client.api \ --model-balíček com. baeldung.petstore.client.model \ --invoker-balíček com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-swagger-codegen-api-client \ --artifact -verzia 0.0.1-SNAPSHOT \ -l java \ --library resttemplate \ -o spring-swagger-codegen-api-client

Predložené argumenty pozostávajú z:

• Adresa URL alebo cesta súboru zdrojového naparovania - poskytovaná pomocou -i argument
• Názvy balíkov pre generované triedy - poskytované pomocou –Api-balíček, –Model-balíček, –Invoker-balíček
• Vygenerované vlastnosti projektu Maven –Group-id, –Artifact-id, – Artefaktová verzia
• Programovací jazyk vygenerovaného klienta - poskytovaný pomocou -l
• Implementačný rámec - poskytovaný pomocou –Knižnica
• Výstupný adresár - poskytnutý pomocou -o

Ak chcete zobraziť zoznam všetkých možností týkajúcich sa Java, zadajte nasledujúci príkaz:

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

Swagger Codegen podporuje nasledujúce knižnice Java (dvojice klientov HTTP a knižnice spracovania JSON):

• dres1 - Jersey1 + Jackson
• dres2 - Jersey2 + Jackson
• predstierať - OpenFeign + Jackson
• okhttp-gson - OkHttp + Gson
• dodatočné vybavenie (Zastarané) - Retrofit1 / OkHttp + Gson
• dodatočné vybavenie2 - Retrofit2 / OkHttp + Gson
• rest-template - Spring RestTemplate + Jackson
• kľud - Resteasy + Jackson

V tomto spise sme si vybrali rest-template pretože je súčasťou jarného ekosystému.

3. Vytvorte klienta REST pomocou generátora OpenAPI

OpenAPI Generator je vidlica Swagger Codegen schopná generovať viac ako 50 klientov z ľubovoľných dokumentov so špecifikáciou 2.0 / 3.x OpenAPI.

Zatiaľ čo program Swagger Codegen spravuje spoločnosť SmartBear, generátor OpenAPI spravuje komunita, ktorá zahŕňa viac ako 40 hlavných prispievateľov a tvorcov šablón spoločnosti Swagger Codegen ako zakladajúcich členov tímu.

3.1. Inštalácia

Asi najjednoduchšou a najprenosnejšou metódou inštalácie je použitie npm balík wrapper, ktorý funguje tak, že poskytuje obal CLI na vrchole možností príkazového riadku podporovaných kódom Java. Inštalácia je jednoduchá:

npm install @ openapitools / openapi-generátor-cli -g

Pre tých, ktorí chcú súbor JAR, je ich možné nájsť v Maven Central. Stiahnime si to teraz:

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. Generovať klienta

Po prvé, možnosti pre OpenAPI Generator sú takmer identické s možnosťami pre Swagger Codegen. Najvýznamnejším rozdielom je výmena -l jazyková vlajka s -g príznak generátora, ktorý berie jazyk na vygenerovanie klienta ako parametra.

Ďalej vygenerujme klienta ekvivalentného tomu, ktorého sme vygenerovali pomocou Swagger Codegen pomocou jar príkaz:

java -jar openapi-generator-cli.jar generovať \ -i //petstore.swagger.io/v2/swagger.json \ --api-balíček com.baeldung.petstore.client.api \ --model-balíček com. baeldung.petstore.client.model \ --invoker-balíček com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-openapi-generator-api-client \ --artifact -verzia 0.0.1-SNAPSHOT \ -g java \ -p java8 = true \ --library resttemplate \ -o spring-openapi-generator-api-client

Ak chcete zobraziť zoznam všetkých možností týkajúcich sa Javy, zadajte príkaz:

java -jar openapi-generátor-cli.jar konfiguračná pomoc -g java

OpenAPI Generator podporuje všetky rovnaké knižnice Java ako Swagger CodeGen a niekoľko ďalších. OpenAPI Generator podporuje nasledujúce knižnice Java (dvojice klientov HTTP a knižnice spracovania JSON):

• dres1 - Jersey1 + Jackson
• dres2 - Jersey2 + Jackson
• predstierať - OpenFeign + Jackson
• okhttp-gson - OkHttp + Gson
• dodatočné vybavenie (Zastarané) - Retrofit1 / OkHttp + Gson
• dodatočné vybavenie2 - Retrofit2 / OkHttp + Gson
• resttemplate - Spring RestTemplate + Jackson
• webový klient - Jar 5 WebClient + Jackson (iba generátor OpenAPI)
• pokojný - Resteasy + Jackson
• vertx - VertX + Jackson
• google-api-client - Google API Client + Jackson
• pokojný - istota + Jackson / Gson (iba Java 8)
• domorodec - natívny Java HttpClient + Jackson (iba Java 11; iba generátor OpenAPI)
• mikroprofil - Mikroprofilový klient + Jackson (iba generátor OpenAPI)

4. Vytvorte projekt Spring Boot

Poďme teraz vytvoriť nový projekt Spring Boot.

4.1. Maven závislosť

Najskôr do nášho projektu pridáme závislosť knižnice Generated API Client pom.xml spis:

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

4.2. Vystavte triedy API ako jarné fazule

Pre prístup k vygenerovaným triedam ich musíme nakonfigurovať ako fazuľa:

@Configuration public class PetStoreIntegrationConfig {@Bean public PetApi petApi () {return new PetApi (apiClient ()); } @Bean public ApiClient apiClient () {vrátiť nový ApiClient (); }}

4.3. Konfigurácia klienta API

The ApiClient trieda sa používa na konfiguráciu autentifikácie, základnej cesty API, bežných hlavičiek a je zodpovedná za vykonávanie všetkých požiadaviek API.

Napríklad ak pracujete s OAuth:

@Bean public ApiClient apiClient () {ApiClient apiClient = nový ApiClient (); OAuth petStoreAuth = (OAuth) apiClient.getAuthentication ("petstore_auth"); petStoreAuth.setAccessToken ("špeciálny kľúč"); návrat apiClient; }

4.4. Jarná hlavná aplikácia

Musíme importovať novo vytvorenú konfiguráciu:

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

4.5. Využitie API

Pretože sme naše triedy API nakonfigurovali ako fazuľa, môžeme ich voľne vložiť do našich tried spravovaných na jar:

@Autowired private PetApi petApi; public List findAvailablePets () {return petApi.findPetsByStatus (Arrays.asList ("available")); }

5. Alternatívne riešenia

Existujú aj iné spôsoby generovania klienta REST, ako je spustenie Swagger Codegen alebo OpenAPI Generator CLI.

5.1. Maven Plugin

Swagger-codegen Maven plugin, ktorý je možné ľahko nakonfigurovať vo vašom pom.xml umožňuje generovanie klienta s rovnakými možnosťami ako Swagger Codegen CLI.

Toto je základný útržok kódu, ktorý môžeme zahrnúť do projektu pom.xml automaticky generovať klienta:

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

5.2. Swagger Codegen Online Generator API

Už zverejnené API, ktoré nám pomáha s generovaním klienta zaslaním požiadavky POST na adresu URL //generator.swagger.io/api/gen/clients/java zadanie adresy URL špecifikácie spolu s ďalšími možnosťami v tele žiadosti.

Ukážme si príklad pomocou jednoduchého príkazu zvlnenia:

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

Odpoveďou by bol formát JSON, ktorý obsahuje odkaz na stiahnutie, ktorý obsahuje vygenerovaný kód klienta vo formáte zip. Môžete prispôsobiť rovnaké možnosti, aké sa používajú v rozhraní Swaager Codegen CLI na prispôsobenie výstupného klienta.

//generator.swagger.io obsahuje dokumentáciu Swagger k API, kde si môžeme skontrolovať jej dokumentáciu a vyskúšať ju.

5.3. OpenAPI Generator Online generátor API

Rovnako ako Swagger Godegen, aj OpenAPI Generator má online generátor. Ukážme si príklad pomocou jednoduchého príkazu zvlnenia:

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

Odpoveď vo formáte JSON bude obsahovať odkaz na vygenerovaný kód klienta, ktorý je možné stiahnuť, vo formáte zip. Môžete prispôsobiť rovnaké možnosti, aké sa používajú v rozhraní Swagger Codegen CLI na prispôsobenie výstupného klienta.

//github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md obsahuje dokumentáciu k API.

6. Záver

Swagger Codegen a OpenAPI Generator vám umožňujú rýchlo generovať klientov REST pre vaše API s mnohými jazykmi a s knižnicou podľa vášho výberu. Knižnicu klientov môžeme vygenerovať pomocou nástroja CLI, doplnku Maven alebo online API.

Toto je projekt založený na Maven, ktorý obsahuje tri moduly Maven: vygenerovaného klienta Swagger API, vygenerovaného klienta OpenAPI a aplikáciu Spring Boot.

Ako vždy, kód nájdete na stránkach GitHub.