TOC

Gere o cliente REST do Spring Boot com Swagger

Gere o cliente REST do Spring Boot com Swagger

1. Introdução

Neste artigo, usaremos o projetoSwagger CodeGen para gerar um cliente REST a partir de um arquivoOpenAPI/Swagger spec.

Além disso, criaremos um projeto Spring Boot, onde usaremos as classes geradas.

Usaremos o exemplo de APISwagger Petstore para tudo.

2. Gerar cliente REST

O Swagger fornece um jar de utilitário que nos permite gerar clientes REST para várias linguagens de programação e várias estruturas.

2.1. Baixar arquivo Jar

Ocode-gen_cli.jar pode ser baixado dehere.

Para a versão mais recente, verifique o repositórioswagger-codegen-cli.

2.2. Gerar Cliente

Vamos gerar nosso cliente executando o comandojava -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

Os argumentos fornecidos consistem em:

  • Um URL ou caminho de arquivo swagger de origem - fornecido usando o argumento-i

  • Nomes de pacotes para classes geradas - fornecidos usando–api-package,–model-package,–invoker-package

  • Propriedades do projeto Maven geradas–group-id,–artifact-id,–artifact-version

  • A linguagem de programação do cliente gerado - fornecida usando-l

  • A estrutura de implementação - fornecida usando o–library

  • O diretório de saída - fornecido usando-o

Para listar todas as opções relacionadas ao Java, digite o seguinte comando: 

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

O Swagger Codegen suporta as seguintes bibliotecas Java (pares de clientes HTTP e bibliotecas de processamento JSON):

  • jersey1 - Jersey1 + Jackson

  • jersey2 - Jersey2 + Jackson

  • feign - OpenFeign + Jackson

  • okhttp-gson - OkHttp + Gson

  • retrofit (obsoleto) - Retrofit1 / OkHttp + Gson

  • retrofit2 - Retrofit2 / OkHttp + Gson

  • rest-template - Spring RestTemplate + Jackson

  • rest-easy - Resteasy + Jackson

Neste artigo, escolhemosrest-template, pois é parte do ecossistema Spring.

3. Gerar Projeto Spring Boot

Vamos agora criar um novo projeto Spring Boot.

3.1. Dependência do Maven

Primeiro, adicionaremos a dependência da biblioteca cliente API gerada - ao arquivopom.xml do nosso projeto: 


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

3.2. Expor classes de API como Spring Beans

Para acessar as classes geradas, precisamos configurá-las como beans: 

@Configuration
public class PetStoreIntegrationConfig {

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

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

3.3. Configuração de cliente API

A classeApiClient é usada para configurar a autenticação, o caminho base da API, cabeçalhos comuns e é responsável por executar todas as solicitações da API.

Por exemplo, se você estiver trabalhando com OAuth: 

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

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

    return apiClient;
}

3.4. Aplicação principal da mola

Precisamos importar a configuração recém-criada: 

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

3.5. Uso de API

Como configuramos nossas classes de API como beans, podemos injetá-las livremente em nossas classes gerenciadas pelo Spring: 

@Autowired
private PetApi petApi;

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

4. Soluções alternativas

Existem outras maneiras de gerar um cliente REST que não seja a execução do Swagger Codegen CLI.

4.1. Maven Plugin

Umswagger-codegen Maven plugin que pode ser configurado facilmente em seupom.xml permite gerar o cliente com as mesmas opções do Swagger Codegen CLI.

Este é um snippet de código básico que podemos incluir nopom.xml do nosso projeto para gerar o cliente automaticamente: 


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

4.2. API Online Generator

Uma API já publicada que nos ajuda a gerar o cliente enviando uma solicitação POST para a URLhttp://generator.swagger.io/api/gen/clients/java passando a URL de especificação junto com outras opções no corpo da solicitação.

Vamos fazer um exemplo usando um comando curl simples: 

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

A resposta seria o formato JSON que contém um link para download que contém o código do cliente gerado no formato zip. Você pode passar as mesmas opções usadas na Swaager Codegen CLI para personalizar o cliente de saída.

https://generator.swagger.io contém uma documentação Swagger para a API, onde podemos verificar sua documentação e testá-la.

5. Conclusão

O Swagger Codegen permite gerar clientes REST rapidamente para sua API com vários idiomas e com a biblioteca de sua escolha. Podemos gerar a biblioteca do cliente usando a ferramenta CLI, o plug-in Maven ou a API online.

A implementação deste exemplo pode ser encontrada nesteGitHub project. Este é um projeto baseado no Maven que contém dois módulos do Maven, o cliente da API gerado e o aplicativo Spring Boot.

Related