Genere un cliente REST de Spring Boot con Swagger

1. Introducción

En este artículo, usaremos los proyectos Swagger Codegen y OpenAPI Generator para generar clientes REST a partir de un archivo de especificaciones OpenAPI / Swagger.

Además, crearemos un proyecto Spring Boot, donde usaremos clases generadas.

Usaremos el ejemplo de la API Swagger Petstore para todo.

2. Genere un cliente REST con Swagger Codegen

Swagger proporciona un jar de utilidades que nos permite generar clientes REST para varios lenguajes de programación y múltiples marcos.

2.1. Descargar archivo Jar

El código-gen_cli.jar se puede descargar desde aquí.

Para obtener la versión más reciente, consulte el repositorio swagger-codegen-cli.

2.2. Generar cliente

Generemos nuestro cliente ejecutando el comando java -jar swagger-code-gen-cli.jar generate:

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

Los argumentos proporcionados consisten en:

  • Una URL o ruta de archivo de swagger de origen, proporcionada mediante el argumento -i
  • Nombres de paquetes para las clases generadas: se proporcionan mediante –api-package , –model-package , –invoker-package
  • Propiedades del proyecto de Maven generadas –group-id , –artifact-id , –artifact-version
  • El lenguaje de programación del cliente generado - proporcionado usando -l
  • El marco de implementación - proporcionado usando la –library
  • El directorio de salida, proporcionado usando -o

Para enumerar todas las opciones relacionadas con Java, escriba el siguiente comando:

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

Swagger Codegen admite las siguientes bibliotecas de Java (pares de clientes HTTP y bibliotecas de procesamiento JSON):

  • jersey1 - Jersey1 + Jackson
  • jersey2 - Jersey2 + Jackson
  • fingir - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • retrofit (obsoleto) - Retrofit1 / OkHttp + Gson
  • retrofit2 - Retrofit2 / OkHttp + Gson
  • plantilla de descanso - Spring RestTemplate + Jackson
  • descansa tranquilo - Resteasy + Jackson

En este artículo, elegimos rest-template ya que es parte del ecosistema Spring.

3. Genere un cliente REST con OpenAPI Generator

OpenAPI Generator es una bifurcación de Swagger Codegen capaz de generar más de 50 clientes a partir de cualquier documento OpenAPI Specification 2.0 / 3.x.

Mientras que Swagger Codegen es mantenido por SmartBear, OpenAPI Generator es mantenido por una comunidad que incluye a más de 40 de los principales contribuyentes y creadores de plantillas de Swagger Codegen como miembros fundadores del equipo.

3.1. Instalación

Quizás el método de instalación más fácil y portátil es usar la envoltura del paquete npm , que funciona proporcionando una envoltura CLI encima de las opciones de línea de comandos compatibles con el código Java. La instalación es sencilla:

npm install @openapitools/openapi-generator-cli -g

Para aquellos que quieran el archivo JAR, se puede encontrar en Maven Central. Vamos a descargarlo ahora:

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. Generar cliente

Primero, las opciones para OpenAPI Generator son casi idénticas a las de Swagger Codegen. La diferencia más notable es el reemplazo del indicador de idioma -l por el indicador de generador -g , que toma el idioma para generar el cliente como parámetro.

A continuación, generemos un cliente equivalente al que generamos con Swagger Codegen usando el comando jar :

java -jar openapi-generator-cli.jar generate \ -i //petstore.swagger.io/v2/swagger.json \ --api-package com.baeldung.petstore.client.api \ --model-package com.baeldung.petstore.client.model \ --invoker-package com.baeldung.petstore.client.invoker \ --group-id com.baeldung \ --artifact-id spring-openapi-generator-api-client \ --artifact-version 0.0.1-SNAPSHOT \ -g java \ -p java8=true \ --library resttemplate \ -o spring-openapi-generator-api-client

Para enumerar todas las opciones relacionadas con Java, escriba el comando:

java -jar openapi-generator-cli.jar config-help -g java

OpenAPI Generator admite todas las mismas bibliotecas de Java que Swagger CodeGen y algunas más. Las siguientes bibliotecas de Java (pares de clientes HTTP y bibliotecas de procesamiento JSON) son compatibles con OpenAPI Generator:

  • jersey1 - Jersey1 + Jackson
  • jersey2 - Jersey2 + Jackson
  • fingir - OpenFeign + Jackson
  • okhttp-gson - OkHttp + Gson
  • retrofit (obsoleto) - Retrofit1 / OkHttp + Gson
  • retrofit2 - Retrofit2 / OkHttp + Gson
  • resttemplate - Spring RestTemplate + Jackson
  • webclient - Spring 5 WebClient + Jackson (API abierta Generador solamente)
  • resteasy - Resteasy + Jackson
  • vertx - VertX + Jackson
  • google-api-client - Cliente API de Google + Jackson
  • Descanse tranquilo - Descanse tranquilo + Jackson / Gson (solo Java 8)
  • nativo : HttpClient + Jackson nativo de Java (solo Java 11; solo generador OpenAPI)
  • microperfil : cliente de microperfil + Jackson (solo generador OpenAPI)

4. Generar proyecto Spring Boot

Let's now create a new Spring Boot project.

4.1. Maven Dependency

We'll first add the dependency of the Generated API Client library – to our project pom.xml file:

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

4.2. Expose API Classes as Spring Beans

To access the generated classes, we need to configure them as beans:

@Configuration public class PetStoreIntegrationConfig { @Bean public PetApi petApi() { return new PetApi(apiClient()); } @Bean public ApiClient apiClient() { return new ApiClient(); } }

4.3. API Client Configuration

The ApiClient class is used for configuring authentication, the base path of the API, common headers, and it's responsible for executing all API requests.

For example, if you're working with OAuth:

@Bean public ApiClient apiClient() { ApiClient apiClient = new ApiClient(); OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth"); petStoreAuth.setAccessToken("special-key"); return apiClient; }

4.4. Spring Main Application

We need to import the newly created configuration:

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

4.5. API Usage

Since we configured our API classes as beans, we can freely inject them in our Spring-managed classes:

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

5. Alternative Solutions

There are other ways of generating a REST client other than executing Swagger Codegen or OpenAPI Generator CLI.

5.1. Maven Plugin

A swagger-codegen Maven plugin that can be configured easily in your pom.xml allows generating the client with the same options as Swagger Codegen CLI.

This is a basic code snippet that we can include in our project's pom.xml to generate client automatically:

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

5.2. Swagger Codegen Online Generator API

An already published API that helps us with generating the client by sending a POST request to the URL //generator.swagger.io/api/gen/clients/java passing the spec URL alongside with other options in the request body.

Let's do an example using a simple curl command:

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

The response would be JSON format that contains a downloadable link that contains the generated client code in zip format. You may pass the same options used in the Swaager Codegen CLI to customize the output client.

//generator.swagger.io contains a Swagger documentation for the API where we can check its documentation and try it.

5.3. OpenAPI Generator Online Generator API

Like Swagger Godegen, OpenAPI Generator also has an online generator. Let's perform an example using a simple curl command:

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

The response, in JSON format, will contain a downloadable link to the generated client code in zip format. You may pass the same options used in the Swagger Codegen CLI to customize the output client.

//github.com/OpenAPITools/openapi-generator/blob/master/docs/online.md contains the documentation for the API.

6. Conclusion

Swagger Codegen y OpenAPI Generator le permiten generar clientes REST rápidamente para su API con muchos idiomas y con la biblioteca de su elección. Podemos generar la biblioteca de cliente utilizando una herramienta CLI, un complemento de Maven o una API en línea.

Este es un proyecto basado en Maven que contiene tres módulos de Maven: el cliente de la API Swagger generado, el cliente OpenAPI generado y la aplicación Spring Boot.

Como siempre, puede encontrar el código disponible en GitHub.