web-dev-qa-db-fra.com

Comment développer un simple client REST en utilisant Swagger codegen?

J'apprends Swagger et comment générer un client REST à l'aide de Swagger codegen. Je sais comment faire de la documentation avec Swagger, je sais aussi comment générer un simple REST serveur avec Swagger, mais je ne sais pas comment générer un simple REST Client avec Swagger codegen.

Par exemple, j'ai une application simple, c'est un serveur REST et je veux générer un client REST. Puis-je le faire avec Swagger codegen?

Le contrôleur pour le serveur REST:

package com.dgs.spring.springbootswagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@RestController
@RequestMapping("/api/v1")
@Api(value = "Employee Management System", description = "Operations pertaining to employee in Employee Management System")
public class EmployeeController {

     @Autowired
     private EmployeeRepository employeeRepository;

        @ApiOperation(value = "View a list of available employees", response = List.class)
        @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successfully retrieved list"),
            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
        })
     @GetMapping("/employees")
     public List<Employee> getAllEmployees() {
         return employeeRepository.findAll();
     }

     @ApiOperation(value = "Get an employee by Id")   
     @GetMapping("/employees/{id}")
     public ResponseEntity<Employee> getEmployeeById(
             @ApiParam(value = "Employee id from which employee object will retrieve", required = true) @PathVariable(value = "id") Long employeeId)
             throws ResourceNotFoundException {

          Employee employee = employeeRepository.findById(employeeId)
            .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

          return ResponseEntity.ok().body(employee);
     }

     @ApiOperation(value = "Add an employee")
     @PostMapping("/employees")
     public Employee createEmployee(
             @ApiParam(value = "Employee object store in database table", required = true) @Valid @RequestBody Employee employee) {
         return employeeRepository.save(employee);
     }

     @ApiOperation(value = "Update an employee")
     @PutMapping("/employees/{id}")
     public ResponseEntity<Employee> updateEmployee(
             @ApiParam(value = "Employee Id to update employee object", required = true) @PathVariable(value = "id") Long employeeId,
             @ApiParam(value = "Update employee object", required = true) @Valid @RequestBody Employee employeeDetails) throws ResourceNotFoundException {

          Employee employee = employeeRepository.findById(employeeId)
            .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

          employee.setEmail(employeeDetails.getEmail());
          employee.setLastName(employeeDetails.getLastName());
          employee.setFirstName(employeeDetails.getFirstName());
          final Employee updatedEmployee = employeeRepository.save(employee);

          return ResponseEntity.ok(updatedEmployee);
     }

     @ApiOperation(value = "Delete an employee")
     @DeleteMapping("/employees/{id}")
     public Map<String, Boolean> deleteEmployee(
             @ApiParam(value = "Employee Id from which employee object will delete from database table", required = true) @PathVariable(value = "id") Long employeeId)
       throws ResourceNotFoundException {

      Employee employee = employeeRepository.findById(employeeId)
        .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

      employeeRepository.delete(employee);
      Map<String, Boolean> response = new HashMap<>();
      response.put("deleted", Boolean.TRUE);

      return response;
     }
}

Après cela, j'ai développé un client REST simple:

package com.dgs.restclient.controllers;

@Controller
public class UpdateController {

    @Autowired
    private EmployeeRestClient restClient;

    @GetMapping("/showStartUpdate")
    public String showStartCheckin() {
        return "startUpdate";
    }

    @PostMapping("/startUpdate")
    public String startCheckIn(@RequestParam("employeeId") Long employeeId, ModelMap modelMap) {

        Employee employee = restClient.findEmployee(employeeId);
        modelMap.addAttribute("employee", employee);

        return "displayEmployeeDetails";
    }

    @PostMapping("/completeUpdate")
    public String completeCheckIn(@RequestParam("employeeId") Long employeeId,
            @RequestParam("employeeFirstName") String employeeFirstName,
            @RequestParam("employeeLastName") String employeeLastName,
            @RequestParam("employeeEmail") String employeeEmail) {

        EmployeeUpdateRequest employeeUpdateRequest = new EmployeeUpdateRequest();
        employeeUpdateRequest.setId(employeeId);
        employeeUpdateRequest.setFirstName(employeeFirstName);
        employeeUpdateRequest.setLastName(employeeLastName);
        employeeUpdateRequest.setEmail(employeeEmail);
        restClient.updateEmployee(employeeUpdateRequest);

        return "updateConfirmation";
    }

}

Le EmployeeRestClient:

package com.dgs.restclient.integration;

@Component
public class EmployeeRestClientImpl implements EmployeeRestClient {

    private static final String EMPLOYEE_REST_URL = 
            "http://localhost:8080/api/v1/employees/";

    @Override
    public Employee findEmployee(Long id) {

        RestTemplate restTemplate = new RestTemplate();
        Employee employee = restTemplate
                .getForObject(EMPLOYEE_REST_URL + id, Employee.class);

        return employee;
    }

    @Override
    public Employee updateEmployee(EmployeeUpdateRequest request) {

        RestTemplate restTemplate = new RestTemplate();
        restTemplate
                .put(EMPLOYEE_REST_URL + request.getId(), request, Employee.class); 

        Employee employee = restTemplate
                .getForObject(EMPLOYEE_REST_URL + request.getId(), Employee.class);

        return employee;
    }

}

Ce client REST est développé par mes soins et je veux savoir si je peux le faire REST Développement client avec Swagger codegen et comment? Dois-je simplement ajouter le plugin swagger-codegen-maven dans le pom.xml? J'ai entendu parler de l'ajout de ce plugin et d'un fichier yml et Swagger créera le client REST. Tout commentaire sera apprécié!

javaspring-bootswaggerrest-clientswagger-codegen
8
elvis

Oui. Vous pouvez utiliser swagger-codegen-maven-plugin pour générer un client REST. Mais avant cela, vous devez décrire l'API REST en YAML ou JSON en OpenAPI Specification principalement parce que swagger-codegen-maven-plugin seul peut générer un client REST à partir d'un fichier écrit dans cette spécification.

D'autres réponses supposent que vous devez écrire la spécification manuellement tandis que ma solution va plus loin pour générer automatiquement la spécification à partir des codes source du contrôleur REST.

La dernière version d'OpenAPI est la 3.0. Mais basé sur le package de votre annotation swagger importée, vous utilisez la version 2.0 (ou antérieure). Donc ma solution suppose que vous utilisez OpenAPI 2.0.

Génération des spécifications de l'API ouverte

Tout d'abord, vous pouvez utiliser swagger-maven-plugin pour générer une spécification OpenAPI à partir des codes source de RestController. Il analyse essentiellement les annotations Swagger annotées dans le @RestController classes spécifiées dans <locations> et vider la spécification OpenAPI dans /src/main/resources/swagger.json:

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.5</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>true</springmvc>
                <locations>
                    <location>com.dgs.spring.springbootswagger.controller.EmployeeController</location>
                    <location>com.dgs.spring.springbootswagger.controller.FooController</location>
                </locations>
                <schemes>
                    <scheme>http</scheme>
                </schemes>
                <Host>127.0.0.1:8080</Host>
                <basePath>/</basePath>
                <info>
                    <title>My API</title>
                    <version>1.1.1</version>
                </info>
                <swaggerDirectory>${basedir}/src/main/resources/</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Exécutez la commande maven suivante pour démarrer la génération:

mvn clean compile

Génération du client de repos

Après swagger.json est généré, vous pouvez le copier et le coller dans votre projet client (par exemple /src/main/resources/swagger.json). On peut alors utiliser swagger-codegen-maven-plugin pour générer un client HTTP.

Par défaut, il générera le projet maven entier qui inclut des cas de test et d'autres trucs de documentation. Mais ce que je veux, c'est juste les codes sources du HttpClient sans autre chose. Après plusieurs essais et erreurs, je m'installe dans la configuration suivante:

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.7</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${basedir}/src/main/resources/swagger.json</inputSpec>
                <language>Java</language>
                <library>resttemplate</library>
                <output>${project.basedir}/target/generated-sources/</output>

                <apiPackage>com.example.demo.restclient.api</apiPackage>
                <modelPackage>com.example.demo.restclient.model</modelPackage>
                <invokerPackage>com.example.demo.restclient</invokerPackage>

                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <generateApiDocumentation>false</generateApiDocumentation>
                <generateModelDocumentation>false</generateModelDocumentation>
                <configOptions>
                    <dateLibrary>Java8</dateLibrary>
                    <sourceFolder>restclient</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Le client HTTP généré est basé sur RestTemplate et sera généré dans le dossier target/generated-sources/restclient. Vous devrez peut-être configurer votre IDE pour importer le client généré afin de l'utiliser. (Dans le cas d'Eclipse, vous pouvez configurer dans les propriétés du projet ➡️ Java Build Path ➡️ Ajouter le dossier du client de repos généré)

Pour commencer à générer le client, exécutez simplement la commande maven:

mvn clean compile

Pour utiliser le client HTTP généré:

ApiClient apiClient = new ApiClient();

//Override the default API base path configured in Maven
apiClient.setBasePath("http://api.example.com/api");

EmployeeManagementSystemApi api = new EmployeeManagementSystemApi(apiClient);
api.getEmployeeById(1l);

Remarque :

  • Si vous rencontrez javax/xml/bind/annotation/XmlRootElement exception lors de la génération lors de l'utilisation de Java8 +, vous devrez peut-être vous référer à this .
6
Ken Chan

Actualisé:

On a répondu à votre question dans un autre post. Jetez un oeil à: poste connexe

...

Pour info une approche simple en ligne de commande:

Il y a un bon tutoriel sur baeldung à ce sujet: comment créer un client de repos avec swagger codegen

Par exemple. Exécuter la commande:

Java -jar swagger-codegen-cli.jar generate \
  -i http://mydomain/v2/swagger.json \
  --api-package com.mypackage.api \
  --model-package com.mypackage.model \
  --invoker-package com.mypackage.invoker \
  --group-id com.mygroup \
  --artifact-id spring-swagger-codegen-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -l Java \
  --library resttemplate \
  -o spring-swagger-codegen-api-client

Swagger Codegen prend en charge les implémentations client suivantes:

  1. jersey1 + Jackson
  2. Jersey2 + Jackson
  3. Feign + Jackson
  4. OkHttp + Gson
  5. Retrofit2/OkHttp + Gson
  6. Spring RestTemplate + Jackson
  7. Resteasy + Jackson

P.S. Comme vous pouvez le voir, le reste du client est généré à partir de la définition de spécification swagger et il est défini avec l'argument "-i".

6
Ariel Carrera

Swagger Endpoints

Supposons que les points de terminaison Swagger de votre application soient accessibles à l'adresse suivante:

  1. Test de la documentation de l'API JSON Swagger 2.0

    http: // localhost: 8080/v2/api-docs? group = employee

    http: // localhost: 8080/v2/api-docs (si vous n'avez pas défini de groupe nommé employee)

  2. Test de l'interface utilisateur Swagger

    http: // localhost: 8080/swagger-ui.html

Télécharger Swagger Codegen Executable

Vous pouvez télécharger swagger-codegen-cli-2.4.7.jar à partir du référentiel central Maven.

Génération de code client

Maintenant que vous disposez du JAR Swagger Codegen, vous pouvez générer le client REST en exécutant la commande suivante:

Java -jar swagger-codegen-cli-2.4.7.jar generate \
  -i http://localhost:8080/v2/api-docs?group=employee \
  -l Java \
  -o swagger-codegen-client

si aucun regroupement fanfaron,

Java -jar swagger-codegen-cli-2.4.7.jar generate \
  -i http://localhost:8080/v2/api-docs \
  -l Java \
  -o swagger-codegen-client

Les options

Bien que Swagger Codegen CLI soit livré avec un certain nombre d'options, nous utilisons les options qui sont absolument nécessaires pour générer le code client.

  • -i l'URL pointant vers Swagger api docs.
  • -l le langage de programmation du client qui dans ce cas est Java
  • -o le dossier de sortie du code client généré.

Une fois que vous avez exécuté la commande précédente pour générer le code, vous devriez remarquer le message suivant sur votre terminal:

[main] INFO io.swagger.parser.Swagger20Parser - reading from http://localhost:8080/v2/api-docs?group=employee
[main] WARN io.swagger.codegen.ignore.CodegenIgnoreProcessor - Output directory does not exist, or is inaccessible. No file (.swagger-codegen-ignore) will be evaluated.
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/Java/io/swagger/client/model/Employee.Java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/docs/Employee.md
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/Java/io/swagger/client/api/EmployeeControllerApi.Java
...
[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/Java/io/swagger/client/ApiClient.Java
...

Projet client REST

Une fois la génération de code terminée, vous devriez remarquer un gradle/maven projet avec la structure suivante:

__ swagger-codegen-client
  |__ README.md
  |__ build.gradle
  |__ build.sbt
  |__ docs
  |__ git_Push.sh
  |__ gradle
  |__ gradle.properties
  |__ gradlew
  |__ gradlew.bat
  |__ pom.xml
  |__ settings.gradle
  |__ src
     |__ main
        |__ Java
          |__ io.swagger.client.api
             |__ EmployeeControllerApi.Java
     |__ test
        |__ Java
          |__ io.swagger.client.api
             |__ EmployeeControllerApiTest.Java

Un exemple de projet client généré peut être trouvé ici .

Utilisation du client REST

Le projet client contient beaucoup de classes Java. Cependant, la classe la plus importante est la EmployeeControllerApi.Java . C'est la classe qui contient toute la logique pour faire REST classes client.

L'autre classe importante est EmployeeControllerApiTest.Java . Il vous montre comment utiliser le EmployeeControllerApi.Java . Le projet client généré fournit également un fichier README qui est très utile.

Changements d'URL

La classe ApiClient contient des informations relatives à l'établissement d'une connexion client HTTP. Veuillez vous assurer que le basePath de votre REST est correcte. Dans l'exemple généré, le basePath avait un https://localhost:8080 URL au lieu de http://localhost:8080.

Modifications de Java 12

Le projet généré fonctionne bien avec Java 8. Si vous utilisez Java 12, vous devrez ajouter les dépendances suivantes pour effectuer la compilation du projet:

    <dependency>
        <groupId>javax.xml.bind</groupId>
        <artifactId>jaxb-api</artifactId>
        <version>2.3.0</version>
    </dependency>
    <dependency>
        <groupId>com.Sun.xml.bind</groupId>
        <artifactId>jaxb-core</artifactId>
        <version>2.3.0</version>
    </dependency>
    <dependency>
        <groupId>com.Sun.xml.bind</groupId>
        <artifactId>jaxb-impl</artifactId>
        <version>2.3.0</version>
    </dependency>

    <dependency>
        <groupId>javax.annotation</groupId>
        <artifactId>javax.annotation-api</artifactId>
        <version>1.3.2</version>
    </dependency>

Exemple REST Appel

Voici un exemple de création d'un employee en effectuant un appel de méthode REST POST).

Employee employee = new Employee();
employee.setId(3L);
employee.setFirstName("Sam");
employee.setLastName("Fox");
employee.setEmail("[email protected]");

EmployeeControllerApi api = new EmployeeControllerApi();
Employee response = api.createEmployeeUsingPOST(employee);
System.out.println(response);

Vous devriez une réponse similaire à ceci:

class Employee {
    email: [email protected]
    firstName: Sam
    id: 3
    lastName: Fox
}

Vous pouvez trouver un exemple complet ici .

2
Indra Basak

1) Allez sur https://editor.swagger.io créez votre documentation swagger, j'utilise "Swagger Petstore" comme exemple

2) Sélectionnez maintenant Fichier, Importer un fichier et téléchargez le fichier swagger.json téléchargé

3) Ouvrez https://swagger.io/tools/swagger-codegen/

4) Suivez les étapes suivantes:

i) Cloner le référentiel sur le clone git du disque https://github.com/swagger-api/swagger-codegen.git

ii) Exécutez mvn clean package

iii) Copiez le fichier swagger-codegen-cli.jar du dossier cible sur un lecteur local sur votre ordinateur.

iv) Exécutez ensuite la commande suivante pour générer un client:

     Java -jar swagger-codegen-cli.jar -i <json_file> -l python -o my_client

Il y a trois arguments pour cette commande:

 -i Specifies the path to the input file. This can be a URL

 -l Specifies the programming language for the client

 -o Specifies the output directory where the generate code should be located

Swagger Codegen est un projet open source qui permet la génération de bibliothèques clientes API (génération SDK), de stubs de serveur et de documentation automatiquement à partir d'une spécification OpenAPI. Swagger Codegen est disponible pour téléchargement dans le référentiel GitHub, ou peut être généré pour toute API définie par OpenAPI nouvelle ou existante dans la plate-forme SwaggerHub intégrée. SwaggerHub apporte les outils Swagger Editor, UI et Codegen au cloud dans une conception et une documentation d'API intégrées, conçues pour les équipes d'API travaillant avec la spécification Swagger (OpenAPI).

Il existe des plugins pour les outils de construction comme Maven et Gradle, car déjà donnés sur peu de réponses, ne pas ajouter ici

1
vaquar khan

ajouter simplement un plugin swagger ne génère pas de client de repos, vous devez suivre ces étapes comme ci-dessous.

notez la spécification au format YAML. Sur la base du résultat de la spécification, sera généré. Enregistrez la spécification en tant que fichier YAML. Il sera enregistré sous swagger.yaml suivez le tutoriel: https://howtodoinjava.com/swagger2/code-generation-for-rest-api/

0
MangduYogii