Spring Boot REST Client mit Swagger generieren

Generieren Sie einen Spring Boot REST Client mit Swagger

1. Einführung

In diesem Artikel verwenden wir das ProjektSwagger CodeGen, um einen REST-Client aus einerOpenAPI/Swagger spec-Datei zu generieren.

Außerdem erstellen wir ein Spring Boot-Projekt, in dem generierte Klassen verwendet werden.

Wir werden das API-Beispiel vonSwagger Petstorefür alles verwenden.

2. REST-Client generieren

Swagger bietet ein Utility-Jar, mit dem wir REST-Clients für verschiedene Programmiersprachen und mehrere Frameworks generieren können.

2.1. Laden Sie die Jar-Datei herunter

Diecode-gen_cli.jar können vonhere heruntergeladen werden.

Die neueste Version finden Sie im Repository vonswagger-codegen-cli.

2.2. Client generieren

Generieren wir unseren Client, indem wir den Befehljava -jar swagger-code-gen-cli.jar generate: ausführen

java -jar swagger-codegen-cli.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-package com.example.petstore.client.api \
  --model-package com.example.petstore.client.model \
  --invoker-package com.example.petstore.client.invoker \
  --group-id com.example \
  --artifact-id spring-swagger-codegen-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -l java \
  --library resttemplate \
  -o spring-swagger-codegen-api-client

Die angegebenen Argumente bestehen aus:

URL oder Pfad einer Quell-Swagger-Datei - bereitgestellt mit dem Argument-i
Namen von Paketen für generierte Klassen - bereitgestellt mit–api-package,–model-package,–invoker-package
Generierte Maven-Projekteigenschaften–group-id,–artifact-id,–artifact-version
Die Programmiersprache des generierten Clients - bereitgestellt mit-l
Das Implementierungsframework - bereitgestellt mit–library
Das Ausgabeverzeichnis - bereitgestellt mit-o

Geben Sie den folgenden Befehl ein, um alle Java-bezogenen Optionen aufzulisten:

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

Swagger Codegen unterstützt die folgenden Java-Bibliotheken (Paare von HTTP-Clients und JSON-Verarbeitungsbibliotheken):

jersey1 - Jersey1 + Jackson
jersey2 - Jersey2 + Jackson
feign - OpenFeign + Jackson
okhttp-gson - OkHttp + Gson
retrofit (veraltet) - Nachrüstung1 / OkHttp + Gson
retrofit2 - Nachrüstung2 / OkHttp + Gson
rest-template - Spring RestTemplate + Jackson
rest-easy - Resteasy + Jackson

In diesem Artikel haben wirrest-template ausgewählt, da es Teil des Spring-Ökosystems ist.

3. Spring Boot-Projekt generieren

Erstellen wir jetzt ein neues Spring Boot-Projekt.

3.1. Maven-Abhängigkeit

Wir werden zuerst die Abhängigkeit der generierten API-Client-Bibliothek zur Datei unseres Projektspom.xmlhinzufügen:


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

3.2. Stellen Sie API-Klassen als Spring Beans bereit

Um auf die generierten Klassen zugreifen zu können, müssen sie als Beans konfiguriert werden:

@Configuration
public class PetStoreIntegrationConfig {

    @Bean
    public PetApi petApi() {
        return new PetApi(apiClient());
    }

    @Bean
    public ApiClient apiClient() {
        return new ApiClient();
    }
}

3.3. API-Client-Konfiguration

Die KlasseApiClientwird zum Konfigurieren der Authentifizierung, des Basispfads der API und der allgemeinen Header verwendet und ist für die Ausführung aller API-Anforderungen verantwortlich.

Wenn Sie beispielsweise mit OAuth arbeiten:

@Bean
public ApiClient apiClient() {
    ApiClient apiClient = new ApiClient();

    OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth");
    petStoreAuth.setAccessToken("special-key");

    return apiClient;
}

3.4. Spring Hauptanwendung

Wir müssen die neu erstellte Konfiguration importieren:

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

3.5. API-Nutzung

Da wir unsere API-Klassen als Beans konfiguriert haben, können wir sie frei in unsere Spring-Managed-Klassen einfügen:

@Autowired
private PetApi petApi;

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

4. Alternativlösungen

Es gibt andere Möglichkeiten, einen REST-Client zu generieren, als die Ausführung von Swagger Codegen CLI.

4.1. Maven Plugin

Einswagger-codegen Maven plugin, das einfach in Ihrempom.xml konfiguriert werden kann, ermöglicht das Generieren des Clients mit denselben Optionen wie die Swagger Codegen CLI.

Dies ist ein grundlegendes Code-Snippet, das wir inpom.xmlunseres Projekts aufnehmen können, um den Client automatisch zu generieren:


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

4.2. Online Generator API

Eine bereits veröffentlichte API, die uns beim Generieren des Clients hilft, indem eine POST-Anforderung an die URLhttp://generator.swagger.io/api/gen/clients/javagesendet wird, die die Spezifikations-URL zusammen mit anderen Optionen im Anforderungshauptteil übergibt.

Lassen Sie uns ein Beispiel mit einem einfachen Curl-Befehl erstellen:

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

Die Antwort wäre ein JSON-Format, das einen herunterladbaren Link enthält, der den generierten Clientcode im ZIP-Format enthält. Sie können dieselben Optionen wie in der Swagger Codegen-CLI verwenden, um den Ausgabe-Client anzupassen.

https://generator.swagger.io enthält eine Swagger-Dokumentation für die API, in der wir die Dokumentation überprüfen und ausprobieren können.

5. Fazit

Mit Swagger Codegen können Sie schnell REST-Clients für Ihre API in vielen Sprachen und mit der Bibliothek Ihrer Wahl generieren. Wir können die Client-Bibliothek mit dem CLI-Tool, dem Maven-Plugin oder der Online-API generieren.

Die Implementierung dieses Beispiels finden Sie inGitHub project. Dies ist ein Maven-basiertes Projekt, das zwei Maven-Module, den generierten API-Client und die Spring Boot-Anwendung enthält.

TOC