camillacleanne/swagger_blogpessoal

Documentação da API com o Swagger 3.0

Nesta atividade iremos implementar a Documentação da nossa API com o Swagger.

Boas Práticas

1. Configure as Dependências no arquivo pom.xml
2. Crie o arquivo SwaggerConfig na Camada Configuration
3. Atualização da Classe Usuario na Camada Model
4. Execute o Swagger
5. Defina o Swagger como a página principal da API
6. Gere o PDF da Documentação

#Passo 1 - Dependências

Configurando o pom.xml

Insira a seguinte dependência no projeto:

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>

#Passo 2 - SwaggerConfig

Crie uma nova package no seu projeto chamada configuration , dentro dela crie uma classe chamada SwaggerConfig e configure segundo o modelo abaixo:

package  br.org.generation.blogpessoal.configuration;

import  java.util.ArrayList;
import  java.util.List;

import  org.springframework.context.annotation.Bean;
import  org.springframework.context.annotation.Configuration;
import  org.springframework.http.HttpMethod;

import  springfox.documentation.builders.ApiInfoBuilder;
import  springfox.documentation.builders.PathSelectors;
import  springfox.documentation.builders.RequestHandlerSelectors;
import  springfox.documentation.builders.ResponseBuilder;
import  springfox.documentation.service.ApiInfo;
import  springfox.documentation.service.Contact;
import  springfox.documentation.service.Response;
import  springfox.documentation.spi.DocumentationType;
import  springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
		.select()
		.apis(RequestHandlerSelectors
		.basePackage("br.org.generation.blogpessoal.controller"))
		.paths(PathSelectors.any())
		.build()
		.apiInfo(metadata())
		.useDefaultResponseMessages(false)
		.globalResponses(HttpMethod.GET, responseMessage())
		.globalResponses(HttpMethod.POST, responseMessage())
		.globalResponses(HttpMethod.PUT, responseMessage())
		.globalResponses(HttpMethod.DELETE, responseMessage());
	}

	public static ApiInfo metadata() {

		return new ApiInfoBuilder()
			.title("API - Blog Pessoal")
			.description("Projeto API Spring - Blog Pessoal")
			.version("1.0.0")
			.license("Apache License Version 2.0")
			.licenseUrl("https://github.com/rafaelq80")
			.contact(contact())
			.build();
	}

	private static Contact contact() {

		return new Contact("Rafael Queiróz", 
			"https://github.com/rafaelq80", 
			"rafaelproinfo@gmail.com");

	}

	private static List<Response> responseMessage() {

		return new ArrayList<Response>() {

			private static final long serialVersionUID = 1L;

			{
				add(new ResponseBuilder().code("200").description("Sucesso!").build());
				add(new ResponseBuilder().code("201").description("Criado!").build());
				add(new ResponseBuilder().code("400").description("Erro na requisição!").build());
				add(new ResponseBuilder().code("401").description("Não Autorizado!").build());
				add(new ResponseBuilder().code("403").description("Proibido!").build());
				add(new ResponseBuilder().code("404").description("Não Encontrado!").build());
				add(new ResponseBuilder().code("500").description("Erro!").build());
			}
		};

	}
}

#Passo 03 - Alteração na Classe Usuario

Vamos configurar o atributo usuario, da Classe Usuario, para emitir um lembrete no Swagger de que deve ser digitado um e-mail no valor do atributo. Para isso, utilizaremos a anotação @ApiModelProperty.

Abra o arquivo Usuario, da Camada Model, localize o atributo usuario e altere de:

@NotNull(message = "O atributo Usuário é Obrigatório!")
@Email(message = "O atributo Usuário deve ser um email válido!")
private String usuario;

Para:

@ApiModelProperty(example = "email@email.com.br")
@NotNull(message = "O atributo Usuário é Obrigatório!")
@Email(message = "O atributo Usuário deve ser um email válido!")
private String usuario;

Observe na figura abaixo que o Swagger indicará que o atributo usuario deve ser um e-mail, ou seja, um exemplo do que deve ser digitado no atributo:

#Passo 4 - Executando o Swagger

Inicie a API, abra o seu navegador na Internet e digite o endereço abaixo para abrir a sua documentação.

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

Em aplicações com camadas de segurança, você precisará logar com uma conta de usuário antes de exibir a sua documentação no Swagger. Insira um usuário cadastrado no Banco de Dados local via Postman para fazer o login.

Pronto! A sua documentação no Swagger está funcionando.

#Passo 5 - Definindo o Swagger como página principal da API

Vamos configurar o Swagger como página principal da nossa API, ou seja, ao digitarmos o endereço: http://localhost:8080, ao invés de abrir a página abaixo:

Abriremos a página do Swagger.

Na camada principal do nosso projeto Blog Pessoal (br.org.generation.blogpessoal) vamos abrir o arquivo BlogpessoalApplication

Vamos alterar o arquivo de:

package br.org.generation.blogpessoal;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BlogpessoalApplication {

	public static void main(String[] args) {
		SpringApplication.run(BlogpessoalApplication.class, args);
	}

}

Para:

package br.org.generation.blogpessoal;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.ModelAndView;

@SpringBootApplication
@RestController
@RequestMapping("/")
public class BlogpessoalApplication {

	@GetMapping
	public ModelAndView swaggerUi() {
		
		return new ModelAndView("redirect:/swagger-ui/");
		
	}
	
	public static void main(String[] args) {
		SpringApplication.run(BlogpessoalApplication.class, args);
	}

}

As alterações acima transformam a classe principal da nossa API (BlogpessoalApplication) em uma classe do tipo RestController, que responderá à todas as requisições do tipo GET para o endpoint "/" (raiz do nosso projeto) e fará o redirecionamento para o Swagger, ou seja, o Swagger será a página home do nosso projeto.

#Passo 6 - Gerando o PDF da Documentação

1. No Swagger, clique no link: http://localhost:8080/v2/api-docs para visualizar a documentação no formato JSON.

2. Visualize o código no formato Raw Data (No Chrome e no Edge é o formato padrão), Selecione todo o código (Ctrl + A) e Copie (Ctrl + C).

3. Acesse o site Swagger Editor (https://editor.swagger.io/).

4. No Swagger Editor, apague o código exemplo e cole o código copiado da Documentação dentro do Editor (Ctrl + V).

5. O Swagger Editor perguntará se você deseja converter o código JSON em YAML. Clique em OK para converter.

6. No Menu Edit, selecione a opção Convert to OpenAPI3

7. Em seguida, clique na guia Convert

8. No menu Generate Client, selecione a opção html2.

9. O Swagger Editor solicitará o download do arquivo html2-client-generated.zip. Faça o download do arquivo, descompacte no seu computador e abra o arquivo index.html no seu navegador.

10 No seu navegador, no menu principal, clique em Imprimir.

11. Na janela de impressão, no item Destino, selecione a opção Salvar em PDF e clique no Botão Salvar.

12. Documentação em PDF gerada!

Referências

Documentação Oficial do Swagger 3.0