TOC

Générer un client REST Spring Boot avec Swagger

Générer un client REST Spring Boot avec Swagger

1. introduction

Dans cet article, nous utiliserons le projetSwagger CodeGen pour générer un client REST à partir d'un fichierOpenAPI/Swagger spec.

Nous allons également créer un projet Spring Boot, dans lequel nous utiliserons des classes générées.

Nous utiliserons l'exemple d'APISwagger Petstore pour tout.

2. Générer un client REST

Swagger fournit un fichier jar utilitaire qui nous permet de générer des clients REST pour divers langages de programmation et plusieurs frameworks.

2.1. Télécharger le fichier Jar

Lescode-gen_cli.jar peuvent être téléchargés depuishere.

Pour la dernière version, veuillez vérifier le référentielswagger-codegen-cli.

2.2. Générer un client

Générons notre client en exécutant la commandejava -jar swagger-code-gen-cli.jar generate: 

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

Les arguments fournis consistent en:

  • Une URL ou un chemin de fichier swagger source - fourni à l'aide de l'argument-i

  • Noms des packages pour les classes générées - fournis en utilisant–api-package,–model-package,–invoker-package

  • Propriétés du projet Maven générées–group-id,–artifact-id,–artifact-version

  • Le langage de programmation du client généré - fourni en utilisant-l

  • Le cadre d'implémentation - fourni en utilisant les–library

  • Le répertoire de sortie - fourni avec-o

Pour répertorier toutes les options liées à Java, tapez la commande suivante: 

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

Swagger Codegen prend en charge les bibliothèques Java suivantes (paires de clients HTTP et bibliothèques de traitement JSON):

  • jersey1 - Maillot1 + Jackson

  • jersey2 - Jersey2 + Jackson

  • feign - OpenFeign + Jackson

  • okhttp-gson - OkHttp + Gson

  • retrofit (obsolète) - Retrofit1 / OkHttp + Gson

  • retrofit2 - Rénovation2 / OkHttp + Gson

  • rest-template - Spring RestTemplate + Jackson

  • rest-easy - Resteasy + Jackson

Dans cet article, nous avons choisirest-template car il fait partie de l'écosystème Spring.

3. Générer un projet Spring Boot

Créons maintenant un nouveau projet Spring Boot.

3.1. Dépendance Maven

Nous allons d'abord ajouter la dépendance de la bibliothèque Generated API Client - à notre fichier projectpom.xml: 


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

3.2. Exposer les classes d'API en tant que Spring Beans

Pour accéder aux classes générées, nous devons les configurer en tant que beans: 

@Configuration
public class PetStoreIntegrationConfig {

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

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

3.3. Configuration du client API

La classeApiClient est utilisée pour configurer l'authentification, le chemin de base de l'API, les en-têtes communs et elle est responsable de l'exécution de toutes les demandes d'API.

Par exemple, si vous travaillez avec OAuth: 

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

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

    return apiClient;
}

3.4. Application principale de printemps

Nous devons importer la configuration nouvellement créée: 

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

3.5. Utilisation de l'API

Puisque nous avons configuré nos classes d'API en tant que beans, nous pouvons les injecter librement dans nos classes gérées par Spring: 

@Autowired
private PetApi petApi;

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

4. Solutions alternatives

Il existe d'autres moyens de générer un client REST que d'exécuter Swagger Codegen CLI.

4.1. Plugin Maven

Unswagger-codegen Maven plugin qui peut être configuré facilement dans vospom.xml permet de générer le client avec les mêmes options que Swagger Codegen CLI.

Voici un extrait de code de base que nous pouvons inclure dans lespom.xml de notre projet pour générer automatiquement le client: 


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

4.2. API de générateur en ligne

Une API déjà publiée qui nous aide à générer le client en envoyant une requête POST à ​​l'URLhttp://generator.swagger.io/api/gen/clients/java en passant l'URL de spécification avec d'autres options dans le corps de la requête.

Faisons un exemple en utilisant une simple commande curl: 

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

La réponse serait au format JSON contenant un lien téléchargeable contenant le code client généré au format zip. Vous pouvez transmettre les mêmes options que celles utilisées dans la CLI Swaager Codegen pour personnaliser le client de sortie.

https://generator.swagger.io contient une documentation Swagger pour l'API où nous pouvons vérifier sa documentation et l'essayer.

5. Conclusion

Swagger Codegen vous permet de générer rapidement des clients REST pour votre API avec plusieurs langues et avec la bibliothèque de votre choix. Nous pouvons générer la bibliothèque cliente à l’aide de l’outil CLI, du plug-in Maven ou de l’API en ligne.

L'implémentation de cet exemple se trouve dans ceGitHub project. Il s'agit d'un projet basé sur Maven qui contient deux modules Maven, le client API généré et l'application Spring Boot.

Related