Genereer Spring Boot REST Client met Swagger

1. Inleiding

In dit artikel gebruiken we de Swagger Codegen- en OpenAPI Generator-projecten om REST-clients te genereren vanuit een OpenAPI / Swagger-specificatiebestand.

We zullen ook een Spring Boot-project maken, waarin we gegenereerde klassen gebruiken.

We zullen het Swagger Petstore API-voorbeeld voor alles gebruiken.

2. Genereer REST Client met Swagger Codegen

Swagger biedt een hulpprogramma-jar waarmee we REST-clients kunnen genereren voor verschillende programmeertalen en meerdere frameworks.

2.1. Jar-bestand downloaden

De code-gen_cli.jar kan hier worden gedownload.

Kijk voor de nieuwste versie in de swagger-codegen-cli repository.

2.2. Genereer Client

Laten we onze client genereren door het commando uit te voeren java -jar swagger-code-gen-cli.jar genereren:

java -jar swagger-codegen-cli.jar genereren \ -i //petstore.swagger.io/v2/swagger.json \ --api-pakket com.baeldung.petstore.client.api \ --model-pakket com. baeldung.petstore.client.model \ --invoker-pakket com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-swagger-codegen-api-client \ --artifact -versie 0.0.1-SNAPSHOT \ -l java \ --bibliotheek resttemplate \ -o spring-swagger-codegen-api-client

De aangevoerde argumenten bestaan uit:

De URL of het pad van een bron-swaggerbestand - opgegeven met de -ik argument
Namen van pakketten voor gegenereerde klassen - verstrekt met –Api-pakket, –Model-pakket, –Invoker-pakket
Gegenereerde Maven-projecteigenschappen -Groep-id, –Artefact-id, -Artefact-versie
De programmeertaal van de gegenereerde client - geleverd met -l
Het implementatiekader - geleverd met behulp van de -bibliotheek
De uitvoermap - geleverd met -O

Typ de volgende opdracht om alle Java-gerelateerde opties weer te geven:

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

Swagger Codegen ondersteunt de volgende Java-bibliotheken (paren van HTTP-clients en JSON-verwerkingsbibliotheken):

trui1 - Jersey1 + Jackson
trui2 - Jersey2 + Jackson
veinzen - OpenFeign + Jackson
okhttp-gson - OkHttp + Gson
achteraf inbouwen (Verouderd) - Retrofit1 / OkHttp + Gson
inbouw achteraf 2 - Achteraf inbouwen2 / OkHttp + Gson
rest-sjabloon - Spring Rest-sjabloon + Jackson
rust gemakkelijk - Resteasy + Jackson

In dit artikel hebben we gekozen rest-sjabloon omdat het deel uitmaakt van het Spring-ecosysteem.

3. Genereer REST Client met OpenAPI Generator

OpenAPI Generator is een splitsing van Swagger Codegen die in staat is om meer dan 50 clients te genereren uit alle OpenAPI Specification 2.0 / 3.x-documenten.

Terwijl Swagger Codegen wordt onderhouden door SmartBear, wordt OpenAPI Generator onderhouden door een community met meer dan 40 van de beste bijdragers en sjabloonmakers van Swagger Codegen als oprichtende teamleden.

3.1. Installatie

Misschien is de gemakkelijkste en meest draagbare installatiemethode het gebruik van de npm pakketwrapper, die werkt door een CLI-wrapper aan te bieden bovenop de opdrachtregelopties die worden ondersteund door de Java-code. De installatie is eenvoudig:

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

Voor degenen die het JAR-bestand willen, het is te vinden in Maven Central. Laten we het nu downloaden:

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. Genereer Client

Ten eerste zijn de opties voor OpenAPI Generator bijna identiek aan die voor Swagger Codegen. Het meest opvallende verschil is de vervanging van de -l taalvlag met de -g generator vlag, die de taal gebruikt om de client als parameter te genereren.

Laten we vervolgens een client genereren die gelijk is aan degene die we hebben gegenereerd met Swagger Codegen met behulp van de pot opdracht:

java -jar openapi-generator-cli.jar genereren \ -i //petstore.swagger.io/v2/swagger.json \ --api-pakket com.baeldung.petstore.client.api \ --model-pakket com. baeldung.petstore.client.model \ --invoker-pakket com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-openapi-generator-api-client \ --artifact -versie 0.0.1-SNAPSHOT \ -g java \ -p java8 = true \ --bibliotheek resttemplate \ -o spring-openapi-generator-api-client

Om alle Java-gerelateerde opties weer te geven, typ je de volgende opdracht:

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

OpenAPI Generator ondersteunt dezelfde Java-bibliotheken als Swagger CodeGen plus een paar extra. De volgende Java-bibliotheken (paren van HTTP-clients en JSON-verwerkingsbibliotheken) worden ondersteund door OpenAPI Generator:

trui1 - Jersey1 + Jackson
trui2 - Jersey2 + Jackson
veinzen - OpenFeign + Jackson
okhttp-gson - OkHttp + Gson
achteraf inbouwen (Verouderd) - Retrofit1 / OkHttp + Gson
inbouw achteraf 2 - Achteraf inbouwen2 / OkHttp + Gson
resttemplate - Spring Rest-sjabloon + Jackson
web cliënt - Spring 5 WebClient + Jackson (alleen OpenAPI Generator)
rustgevend - Resteasy + Jackson
vertx - VertX + Jackson
google-api-client - Google API-client + Jackson
wees gerustgesteld - wees gerust + Jackson / Gson (alleen Java 8)
native - Java native HttpClient + Jackson (alleen Java 11; alleen OpenAPI Generator)
microprofiel - Microprofile client + Jackson (alleen OpenAPI Generator)

4. Genereer Spring Boot Project

Laten we nu een nieuw Spring Boot-project maken.

4.1. Afhankelijkheid van Maven

We zullen eerst de afhankelijkheid van de Generated API Client-bibliotheek toevoegen aan ons project pom.xml het dossier:

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

4.2. Stel API-klassen bloot als lentebonen

Om toegang te krijgen tot de gegenereerde klassen, moeten we ze configureren als bonen:

@Configuration openbare klasse PetStoreIntegrationConfig {@Bean openbare PetApi petApi () {retourneer nieuwe PetApi (apiClient ()); } @Bean public ApiClient apiClient () {retourneer nieuwe ApiClient (); }}

4.3. API-clientconfiguratie

De ApiClient class wordt gebruikt voor het configureren van authenticatie, het basispad van de API, algemene headers, en is verantwoordelijk voor het uitvoeren van alle API-verzoeken.

Als u bijvoorbeeld met OAuth werkt:

@Bean openbare ApiClient apiClient () {ApiClient apiClient = nieuwe ApiClient (); OAuth petStoreAuth = (OAuth) apiClient.getAuthentication ("petstore_auth"); petStoreAuth.setAccessToken ("speciale sleutel"); retourneer apiClient; }

4.4. Lente hoofdtoepassing

We moeten de nieuw gemaakte configuratie importeren:

@SpringBootApplication @Import (PetStoreIntegrationConfig.class) openbare klasse PetStoreApplication {openbare statische leegte hoofd (String [] args) gooit Uitzondering {SpringApplication.run (PetStoreApplication.class, args); }}

4.5. API-gebruik

Omdat we onze API-klassen als bonen hebben geconfigureerd, kunnen we ze vrijelijk injecteren in onze door Spring beheerde klassen:

@Autowired privé PetApi petApi; openbare lijst findAvailablePets () {retourneer petApi.findPetsByStatus (Arrays.asList ("beschikbaar")); }

5. Alternatieve oplossingen

Er zijn andere manieren om een REST-client te genereren, behalve het uitvoeren van Swagger Codegen of OpenAPI Generator CLI.

5.1. Maven-plug-in

Een swagger-codegen Maven-plug-in die eenvoudig kan worden geconfigureerd in uw pom.xml maakt het mogelijk om de client te genereren met dezelfde opties als Swagger Codegen CLI.

Dit is een basiscodefragment dat we kunnen opnemen in het pom.xml om een client automatisch te genereren:

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

5.2. Swagger Codegen Online Generator API

Een reeds gepubliceerde API die ons helpt bij het genereren van de client door een POST-verzoek naar de URL te sturen //generator.swagger.io/api/gen/clients/java het doorgeven van de spec-URL samen met andere opties in de hoofdtekst van het verzoek.

Laten we een voorbeeld doen met een eenvoudig curl-commando:

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

Het antwoord zou een JSON-indeling zijn die een downloadbare link bevat die de gegenereerde clientcode in zip-indeling bevat. U kunt dezelfde opties doorgeven die worden gebruikt in de Swaager Codegen CLI om de uitvoerclient aan te passen.

//generator.swagger.io bevat een Swagger-documentatie voor de API waar we de documentatie kunnen controleren en uitproberen.

5.3. OpenAPI Generator Online Generator API

Net als Swagger Godegen heeft OpenAPI Generator ook een online generator. Laten we een voorbeeld uitvoeren met een eenvoudig curl-commando:

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

Het antwoord, in JSON-indeling, bevat een downloadbare link naar de gegenereerde clientcode in zip-indeling. U kunt dezelfde opties doorgeven die worden gebruikt in de Swagger Codegen CLI om de uitvoerclient aan te passen.

//github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md bevat de documentatie voor de API.

6. Conclusie

Met Swagger Codegen en OpenAPI Generator kunt u snel REST-clients genereren voor uw API met veel talen en met de bibliotheek van uw keuze. We kunnen de clientbibliotheek genereren met behulp van een CLI-tool, Maven-plug-in of online API.

Dit is een op Maven gebaseerd project dat drie Maven-modules bevat: de gegenereerde Swagger API-client, de gegenereerde OpenAPI-client en de Spring Boot-applicatie.

Zoals altijd kun je de code vinden die beschikbaar is op GitHub.

streamalism.org