Uma API bem construída deve ser simples de ser consumida, por isso é fundamental documentar a API da maneira correta. O objetivo da Documentação é apresentar uma espécie de "manual de instruções" que permita que qualquer pessoa (Desenvolvedora ou não), que ainda não tenha pleno conhecimento do domínio da sua aplicação, consuma a API de maneira fácil, rápida, eficaz e autônoma.
A OpenApi, trata-se de uma especificação Open Source, que auxilia as pessoas desenvolvedoras nos processos de definir, criar, documentar e consumir API's REST e RESTful. A OpenApi tem por objetivo padronizar este tipo de integração, descrevendo os recursos que uma API possui, os respectivos endpoints, os dados que serão solicitados nas Requisições, os dados que serão retornados nas Respostas, os Status HTTP, os modelos de dados, os Métodos de autenticação, entre outros.
APIs REST são frequentemente usadas para a integração de aplicações, seja para consumir serviços de terceiros, seja para prover novos serviços. Para estas APIs, a especificação OpenApi facilita a modelagem, a documentação e a geração de código.
Site Oficial: OpenApi
O Swagger é uma poderosa ferramenta que ajuda pessoas Desenvolvedoras a projetar, desenvolver, documentar e consumir serviços web REST e RESTful, de forma interativa e dinâmica, aproveitando ao máximo todos os Recursos da especificação OpenApi. Apesar de ser conhecida principalmente por sua interface Swagger UI, o software inclui suporte para documentação automatizada da API, geração de código e testes.
O Editor Swagger é um editor de código aberto para projetar, definir e documentar APIs RESTful na Especificação Swagger.
A biblioteca Java Springdoc-OpenApi é uma implementação da OpenApi + Swagger, que ajuda a automatizar a geração de documentação API em projetos SpringBoot. A Springdoc-OpenApi examina um aplicativo em tempo de execução para Criar a Documentação da API, com base nas configurações do Spring, na estrutura das Classes e algumas Anotações. A documentação é gerada automaticamente no formato JSON / YAML e HTML. Esta documentação pode ser completada por comentários usando Anotações do Swagger.
 |
ATENÇÃO: Para utilizar o Springdoc com o Spring Boot 3.0 ou superior, obrigatoriamente devemos utilizar a versão 2.0 ou superior do Springdoc. |
|---|
YAML é um formato de serialização (codificação de dados) de dados legíveis por humanos inspirado no XML, sendo amplamente utilizada em arquivos de configuração, assim como o XML e o JSON. YAML é um acrónimo recursivo que significa "YAML Ain't Markup Language" (em português, "YAML não é linguagem de marcação").
Vamos criar a Documentação do nosso Projeto Blog Pessoal no formato Digital através da Biblioteca SpringDoc e no formato Impresso através do Swagger Editor.
Abra o arquivo pom.xml e insira a dependência do SpringDoc:
<!-- Dependência para Geração do Swagger -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency> |
ATENÇÃO: Quando este material foi escrito, a versão atual do Springdoc era a 2.2.0, logo a versão atual pode ser outra. |
|---|
Insira as linhas abaixo no arquivo application.properties, da Source Folder Principal (src/main/resources), logo abaixo da configuração do Banco de dados MySQL:
Linha 16: Define o Caminho para a Documentação do OpenAPI no formato JSON.
Linha 17: Define o Caminho para a Documentação do Swagger-ui no formato HTML.
Linha 18: Define a ordem em que os Recursos serão exibidos no Swagger-ui. Em nosso projeto, os Recursos serão ordenados por Método.
Linha 19: Desabilita a URL padrão do Swagger-ui (Exemplo no site do Swagger).
Linha 20: Define o nome da Package da Camada Controladora (Controller).
 |
ALERTA DE BSM: Mantenha a Atenção aos Detalhes ao criar a configuração do Springdoc no arquivo application.properties. Informar o caminho (path) incorreto da Camada Controller fará com que o Swagger não funcione e seja exibida a mensagem de erro No operations defined in spec!, como mostra a imagem abaixo: |
|---|
Linha 21: Define o Swagger-ui como a página inicial da aplicação.
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.packagesToScan=com.generation.blogpessoal.controller
springdoc.swagger-ui.use-root-path=true |
ATENÇÃO: Não insira comentários no arquivo application.properties. Geralmente, durante o Deploy na nuvem, comentários inseridos no arquivo application.properties podem causar erros de compilação no projeto. |
|---|
A Camada Configuration é responsável por implementar configurações específicas da aplicação. Em nosso Projeto, vamos utilizar esta Camada para implementar a Documentação da API com o Swagger
-
No lado esquerdo superior, na Guia Package explorer, clique com o botão direito do mouse sobre a Package com.generation.blogpessoal, na Source Folder src/main/java e clique na opção New 🡪 Package.
-
Na janela New Java Package, no item Name, acrescente no final do nome da Package .configuration, como mostra a figura abaixo:
-
Clique no botão Finish para concluir.
-
Clique com o botão direito do mouse sobre o Pacote Configuration (com.generation.blogpessoal.configuration), na Source Folder Principal (src/main/java), e na sequência, clique na opção New 🡪 Class
-
Na janela New Java Class, no item Name, digite o nome da Classe (SwaggerConfig), como mostra a figura abaixo:
- Clique no botão Finish para concluir.
Vejamos abaixo a implementação da Classe SwaggerConfig:
Linha 1: Através do comando package, estamos informando o nome do pacote (camada), onde a Classe foi criada. Esta informação é inserida automaticamente pelo STS ao criar a Classe.
Linhas 3 a 13: Através do comando import, estamos indicando todos os pacotes que contém as Classes que estão sendo utilizadas na Classe SwaggerConfig.
Vamos analisar o código:
Linha 15: A Anotação (Annotation) @Configuration indica que a Classe é do tipo configuração, ou seja, define uma Classe como fonte de definições de Beans. A anotação @Configuration é uma das anotações essenciais ao utilizar uma configuração baseada em Java.
Linha 18: A Anotação @Bean utilizada em Métodos de uma Classe, geralmente marcada com @Configuration, indica ao Spring que ele deve invocar aquele Método e gerenciar o objeto retornado por ele, ou seja, agora este objeto pode ser injetado em qualquer ponto da sua aplicação.
Bean: No Spring, os objetos que formam a espinha dorsal da sua aplicação e que são gerenciados pelo Spring são chamados de Beans. Um Bean é um objeto que é instanciado, montado e gerenciado pelo Spring.
Existem diversas formas de se criar Beans no Spring. Você pode criar Classes anotadas com @Configuration ou @Service para serem gerenciadas pelo Spring, assim como pode usar a anotação @Bean em um Método, e transformar a instância retornada pelo Método em um Objeto gerenciado pelo Spring (seja de uma Classe própria ou de terceiros).
Estas Classes, que na visão do Spring são os Beans, para você nada mais são do que Classes que você irá escrever as regras de funcionamento da sua aplicação, que poderão ser utilizadas em qualquer Classe, diferente da Injeção de Dependência criada pela anotação @Autowired, que só permite o uso dentro da Classe em que foi criada.
Linha 20: Cria um Objeto da Classe OpenAPI, que gera a documentação no Swagger utilizando a especificação OpenAPI.
Linhas 21 a 24: Insere as informações sobre a API (Nome do projeto (Title), Descrição e Versão)
Linhas 25 a 27: Insere as informações referentes a licença da API (Nome e Link)
Linhas 28 a 31: Insere as informações de contato da pessoa Desenvolvedora (Nome, Site e e E-mail)
|
ATENÇÃO: As propriedades nome, site e e-mail permitem apenas um nome, um único endereço WEB e um único endereço de e-mail. |
|---|
Linhas 32 a 24: Insere as informações referentes a Documentações Externas (Github, Gitpage e etc), onde são informados o Nome e o Link.
|
ALERTA DE BSM: Mantenha a Atenção aos Detalhes ao criar a Classe SwaggerConfig. As informações de Contato e Documentações Externas devem ser preenchidas com os seus dados (Nome, E-mail, Github e etc). No caso do Projeto Integrador, devem ser preenchidos com os dados do Grupo |
|---|
A Classe OpenApiCustomiser permite personalizar o Swagger, baseado na Especificação OpenAPI. O Método acima, personaliza todas as mensagens HTTP Responses (Respostas das requisições) do Swagger.
Linha 40: Cria um Objeto da Classe OpenAPI, que gera a documentação no Swagger utilizando a especificação OpenAPI.
Linha 41: Cria um primeiro looping que fará a leitura de todos os recursos (Paths) através do Método getPaths(), que retorna o caminho de cada endpoint. Na sequência, cria um segundo looping que Identificará qual Método HTTP (Operations), está sendo executado em cada endpoint através do Método readOperations(). Para cada Método, todas as mensagens serão lidas e substituídas pelas novas mensagens.
Linha 44: Cria um Objeto da Classe ApiResponses, que receberá as Respostas HTTP de cada endpoint (Paths) através do Método getResponses().
Linhas 46 a 53: Adiciona as novas Respostas no endpoint, substituindo as atuais e acrescentando as demais, através do Método addApiResponse(), identificadas pelo HTTP Status Code (200, 201 e etc).
Linhas 59 a 63: O Método createApiResponse() adiciona uma descrição (Mensagem), em cada Resposta HTTP.
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 @Schema.
A anotação @Schema nos permite controlar as definições específicas do Swagger, como descrição (valor), nome, tipo de dados, valores de exemplo e valores permitidos para as propriedades do modelo. No Atributo usuario, vamos utilizar a propriedade example.
Na Classe Usuario, localizada na Camada Model, acrescente no Atributo usuario a anotação abaixo:
@Schema(example = "[email protected]")Após acrescentar a anotação acima, o Atributo usuario terá a seguinte configuração:
@Schema(example = "[email protected]")
@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 imagem abaixo que o Swagger indicará que o Atributo usuario deve ser um endereço de e-mail. Ao testar o Swagger, verifique se esta indicação foi adicionada no Atributo usuario.
Para efetuar essa alteração na Classe Usuario vamos importar um novo pacote, como mostra a imagem abaixo:
Documentação: @Schema
Para abrir o Swagger, precisamos de um usuário para efetuar login na nossa aplicação. Vamos criar o usuário [email protected] para testarmos a nossa API.
- Abra o Insomnia e crie o usuário root com os dados da imagem abaixo:
-
Abra o seu navegador da Internet e digite o endereço http://localhost:8080 para abrir a sua documentação.
-
Faça o login na aplicação com a conta de usuário usuário [email protected], que foi criada anteriormente.
- A Documentação no Swagger será exibida.
- No Swagger, clique no link: http://localhost:8080/v3/api-docs para visualizar a documentação no formato JSON.
- Visualize o código no formato Raw Data ou Dados brutos (No Chrome e no Edge é o formato padrão), Selecione todo o código (Ctrl + A) e Copie (Ctrl + C).
- Acesse o site Swagger Editor (https://editor.swagger.io/).
- No Swagger Editor, apague o código exemplo e cole o código copiado da Documentação dentro do Editor (Ctrl + V).
- O Swagger Editor perguntará se você deseja converter o código JSON em YAML. Clique em OK para converter.
- No menu Generate Client, selecione a opção html2.
- 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, no menu principal, clique em Imprimir.
- Na janela de impressão, no item Destino, selecione a opção Salvar em PDF e clique no Botão Salvar.
- Documentação em PDF gerada!
Voltar