Spring Boot + Swagger: documentando sua API automaticamente
Quem já desenvolveu APIs sabe o quanto é importante que quem as consuma saiba do que se trata e quais os contratos que são firmados no envio e no recebimento de dados. O Swagger é uma das ferramentas mais importantes que visa solucionar esse problema de documentação e outros (que serão tema de futuros artigos que escreverei).
Esta semana iremos criar um projeto simples em Spring Boot que documenta automaticamente o Swagger utilizando uma biblioteca chamada SpringFox. Caso queira já pular para o projeto completo, ele está disponível neste repositório no Github.
Como pré-requisito para acompanhar esse tutorial você precisa ter um conhecimento intermediário na linguagem Java e ao menos básico no framework Spring Boot. Recomendo começar pelos guias disponíveis no site spring.io.
1. Inicializando o projeto
Vamos utilizar o Spring Initializr, a melhor maneira de iniciar um projeto Spring. Acesse e escolha Gradle ao invés de Maven, mas caso seu projeto utilize Maven, não se preocupe, basta baixar o projeto completo ao final do artigo, eu criei um pom.xml também.
Nas dependências, insira apenas Web e Lombok e gere o projeto, importando em sua IDE (eu utilizo Intellij IDEA). Caso não conheça o Lombok, sugiro que dê uma olhada e adote em seus projetos.
2. Configurando o Swagger
Após importar o projeto, abra o build.gradle e insira em dependencies as dependências necessárias para o Swagger (ocultei no exemplo as dependências que já vem configuradas pelo Initializr):
dependencies {
compile('io.springfox:springfox-swagger2:2.9.2')
compile('io.springfox:springfox-swagger-ui:2.9.2')
}Em seguida é preciso configurar o Swagger em seu projeto. Crie uma classe chamada SwaggerConfig e nela insira esse conteúdo:
package com.example.swaggerready;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket greetingApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerready"))
.build()
.apiInfo(metaData());
}
private ApiInfo metaData() {
return new ApiInfoBuilder()
.title("Spring Boot REST API")
.description("\"Spring Boot REST API for greeting people\"")
.version("1.0.0")
.license("Apache License Version 2.0")
.licenseUrl("https://www.apache.org/licenses/LICENSE-2.0\"")
.build();
}
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
Veja que criamos um Bean, não se esqueça de alterar o basePackage para o utilizado em seu projeto (o meu no caso é com.example.swaggerready), e é com base nele que o Swagger irá encontrar seus endpoints para documentar.
3. Vamos ao que interessa
Primeiramente vamos criar no package hello a classe Greeting, que irá representar nossa saudação:
package com.example.swaggerready.hello;import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
public class Greeting {
private String message;
}
Veja que utilizamos anotações do Lombok que dispensam a necessidade de criarmos os construtores e getters/setters.
Agora vamos finalmente ao nosso Controller:
package com.example.swaggerready.hello;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api(value = "Greeting")
public class GreetingController {
@ApiOperation(value = "Greets the world or Niteroi")
@GetMapping(value = "/hello", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public Greeting hello(@RequestParam(required = false) boolean niteroi) {
Greeting greeting = new Greeting("Hello world");
if (niteroi) {
greeting.setMessage(greeting.getMessage().replace("world", "Niteroi"));
}
return greeting;
}
@ApiOperation(value = "Greets a person given her name")
@GetMapping(value = "/hello/{name}", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public Greeting get(@PathVariable String name) {
return new Greeting("Hello, " + name);
}
}A primeira anotação do Swagger que utilizamos é a @Api, onde no nosso exemplo declaramos do que se trata nossa API. Veja que ela é utilizada uma vez no Controller. A outra anotação utilizada é a @ApiOperation, para cada endpoint, declarando do que se trata a operação. Vamos agora fazer a build e rodar a aplicação, e o processo irá disponibilizar o Swagger na URL http://localhost:8080/swagger-ui.html (a porta padrão é 8080, mas no seu projeto pode ter sido configurada para outra porta, verifique no log ao inicializar).
Você pode interagir no Swagger UI e testar facilmente o Controller que criamos. Leia mais sobre o Springfox para aprender como alcançar resultados mais avançados em https://github.com/springfox/springfox .
Isso é tudo por enquanto, fique à vontade para deixar seu comentário.
Relembrando, o projeto utilizado no tutorial está disponível em https://github.com/raphaelbluteau/swagger-ready-spring-boot .
Você pode me acompanhar no meu blog: https://raphaelcarvalho.dev .
