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.