spring-boot-rest-client-swagger-codegen

Posted on: 2019-10-08 2019-11-19
Tags: REST, Spring Boot

Generate Spring Boot REST Client with Swagger

1. Introduction

In this article, we’ll use the Swagger CodeGen project to generate a REST client from an OpenAPI/Swagger spec file.

Also, we’ll create a Spring Boot project, where we’ll use generated classes.

We’ll use the Swagger Petstore API example for everything.

2. Generate REST Client

Swagger provides a utility jar that allows us to generate REST clients for various programming languages and multiple frameworks.

2.1. Download Jar File

The code-gen_cli.jar can be downloaded from here.

For the newest version, please check the swagger-codegen-cli repository.

2.2. Generate Client

Let’s generate our client by executing the command java -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.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

The provided arguments consist of:

A source swagger file URL or path – provided using the -i argument
Names of packages for generated classes – provided using –api-package, –model-package, –invoker-package
Generated Maven project properties –group-id, –artifact-id, –artifact-version
The programming language of the generated client – provided using -l
The implementation framework – provided using the –library
The output directory – provided using -o

To list all Java-related options, type the following command:

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

Swagger Codegen supports the following Java libraries (pairs of HTTP clients and JSON processing libraries):

jersey1 – Jersey1 + Jackson
jersey2 – Jersey2 + Jackson
feign – OpenFeign + Jackson
okhttp-gson – OkHttp + Gson
retrofit (Obsolete) – Retrofit1/OkHttp + Gson
retrofit2 – Retrofit2/OkHttp + Gson
rest-template – Spring RestTemplate + Jackson
rest-easy – Resteasy + Jackson

In this write-up, we chose rest-template as it’s a part of the Spring ecosystem.

3. Generate Spring Boot Project

Let’s now create a new Spring Boot project.

3.1. Maven Dependency

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

<dependency>
    <groupId>com.baeldung</groupId>
    <artifactId>spring-swagger-codegen-api-client</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

3.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();
    }
}

3.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;
}

3.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);
    }
}

3.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<Pet> findAvailablePets() {
    return petApi.findPetsByStatus(Arrays.asList("available"));
}

4. Alternative Solutions

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

4.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:

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.2.3</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>swagger.yaml</inputSpec>
                <language>java</language>
                <library>resttemplate</library>
            </configuration>
        </execution>
    </executions>
</plugin>

4.2. Online Generator API

An already published API that helps us with generating the client by sending a POST request to the URL http://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":"http://petstore.swagger.io/v2/swagger.json"}' \
http://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.

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

5. Conclusion

Swagger Codegen enables you to generate REST clients quickly for you API with many languages and with the library of your choice. We can generate the client library using CLI tool, Maven plugin or Online API.

The implementation of this example can be found in this GitHub project. This is a Maven based project that contains two Maven modules, the generated API client, and the Spring Boot application.

getdocs

3043