Saltar al contenido

¿Cómo desarrollar un cliente REST simple usando Swagger codegen?

Este grupo de trabajo ha estado por horas investigando la solución a tus dudas, te compartimos la respuesta por esto nuestro objetivo es resultarte de gran apoyo.

Solución:

Si. Puedes usar swagger-codegen-maven-plugin para generar un cliente REST. Pero antes de eso, debe describir la API REST en YAML o JSON en OpenAPI Specification principalmente porque swagger-codegen-maven-plugin solo puede generar un cliente REST a partir de un archivo escrito en esta especificación.

Otras respuestas asumen que necesita escribir la especificación manualmente, mientras que mi solución da un paso más para generar automáticamente la especificación a partir de los códigos fuente del controlador REST.

La última versión de OpenAPI es 3.0. Pero según el paquete de su anotación de swagger importada, está utilizando la versión 2.0 (o anterior). Entonces, mi solución asume que está usando OpenAPI 2.0.

Generación de especificación de API abierta

Primero, puede usar swagger-maven-plugin para generar una especificación de OpenAPI a partir de los códigos fuente de RestController. Básicamente analiza las anotaciones Swagger anotadas en el @RestController clases que especifican en y volcar la especificación de OpenAPI a /src/main/resources/swagger.json :


    com.github.kongchen
    swagger-maven-plugin
    3.1.5
    
        
            
                true
                
                    com.dgs.spring.springbootswagger.controller.EmployeeController
                    com.dgs.spring.springbootswagger.controller.FooController
                
                
                    http
                
                127.0.0.1:8080
                /
                
                    My API
                    1.1.1
                
                $basedir/src/main/resources/
            
        
    
    
        
            
                generate
            
        
    

Ejecute el siguiente comando maven para iniciar la generación:

mvn clean compile

Generando cliente de descanso

Después swagger.json se genera, puede copiarlo y pegarlo en el proyecto de su cliente (por ejemplo, /src/main/resources/swagger.json). Entonces podemos usar swagger-codegen-maven-plugin para generar un cliente HTTP.

De forma predeterminada, generará todo el proyecto de maven, que incluye casos de prueba y otras cosas de documentación. Pero lo que quiero son solo los códigos fuente de HttpClient sin otras cosas. Después de varias pruebas y errores, me quedo con la siguiente configuración:


    io.swagger
    swagger-codegen-maven-plugin
    2.4.7
    
        
            
                generate
            
            
                $basedir/src/main/resources/swagger.json
                java
                resttemplate
                $project.basedir/target/generated-sources/

                com.example.demo.restclient.api
                com.example.demo.restclient.model
                com.example.demo.restclient

                false
                false
                false
                false
                
                    java8
                    restclient
                
            
        
    

El cliente HTTP generado se basa en RestTemplate y se generará en la carpeta target/generated-sources/restclient. Es posible que deba configurar su IDE para importar el cliente generado para poder usarlo. (En el caso de Eclipse, puede configurar en Propiedades del proyecto ➡️ Ruta de compilación de Java ➡️ Agregar la carpeta del cliente de descanso generado)

Para comenzar a generar el cliente, simplemente ejecute el comando maven:

mvn clean compile

Para utilizar el cliente HTTP generado:

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);

Nota :

  • Si te cruzas javax/xml/bind/annotation/XmlRootElement excepción durante la generación al usar java8 +, es posible que deba consultar esto.

Actualizado:

Tu pregunta fue respondida en otra publicación. Echa un vistazo a: publicación relacionada

Para su información, un enfoque simple usando la línea de comando:

Hay un buen tutorial en baeldung al respecto: cómo crear un cliente de descanso con swagger codegen

Por ejemplo, ejecutar comando:

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 admite las siguientes implementaciones de clientes:

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

PD: Como puede ver, el cliente restante se genera a partir de la definición de la especificación swagger y se define con el argumento “-i”.

Puntos finales de Swagger

Digamos que se puede acceder a los puntos finales Swagger de su aplicación en:

  1. Prueba de la documentación de la API JSON de Swagger 2.0

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

    http: // localhost: 8080 / v2 / api-docs (si no ha configurado un grupo llamado employee)

  2. Prueba de la interfaz de usuario de Swagger

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

Descarga Swagger Codegen Executable

Puede descargar swagger-codegen-cli-2.4.7.jar desde el repositorio central de Maven.

Generando código de cliente

Ahora que tiene el Swagger Codegen JAR, puede generar el cliente REST ejecutando el siguiente comando:

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 no hay agrupación arrogante,

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

Opciones

Aunque Swagger Codegen CLI viene con una serie de opciones, estamos usando las opciones que son absolutamente necesarias para generar el código del cliente.

  • -i la URL que apunta a la aplicación Swagger api docs.
  • -l el lenguaje de programación del cliente que en este caso es java
  • -o la carpeta de salida para el código de cliente generado.

Una vez que ejecute el comando anterior para generar el código, debería notar el siguiente mensaje en su 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
...

Proyecto de cliente REST

Una vez que se completa la generación del código, debería notar un gradle/maven proyecto con la siguiente estructura:

__ 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

Aquí puede encontrar un ejemplo de un proyecto de cliente generado.

Uso del cliente REST

El proyecto del cliente contiene muchas clases de Java. Sin embargo, la clase más importante es EmployeeControllerApi.java. Esta es la clase que contiene toda la lógica para crear clases de cliente REST.

La otra clase importante es EmployeeControllerApiTest.java. Le muestra cómo utilizar EmployeeControllerApi.java. El proyecto de cliente generado también proporciona un archivo README que es muy útil.

Cambios de URL

La clase ApiClient contiene información relacionada con el establecimiento de una conexión de cliente HTTP. Por favor, asegúrese de basePath
a su aplicación REST es correcta. En el ejemplo generado, el basePath tenía un https://localhost:8080 URL en lugar de http://localhost:8080.

Cambios en Java 12

El proyecto generado funciona bien con Java 8. Si está utilizando Java 12, tendrá que agregar las siguientes dependencias para que el proyecto se compile:

    
        javax.xml.bind
        jaxb-api
        2.3.0
    
    
        com.sun.xml.bind
        jaxb-core
        2.3.0
    
    
        com.sun.xml.bind
        jaxb-impl
        2.3.0
    

    
        javax.annotation
        javax.annotation-api
        1.3.2
    

Ejemplo de llamada de REST

A continuación, se muestra un ejemplo de cómo crear un employee haciendo una llamada al método 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);

Debería una respuesta similar a esta:

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

Puedes encontrar un ejemplo completo aquí.

Reseñas y calificaciones

¡Haz clic para puntuar esta entrada!
(Votos: 0 Promedio: 0)



Utiliza Nuestro Buscador

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *