Criando Documentação para a sua API com o Swagger

_{Autor: Cícero Joasyo Mateus de Moura}

Nesse artigo vamos criar a documentação legível de uma API Rest utilizando o Spring Boot 2 e o Swagger 2 na linguagem Java. 

Primeiramente vamos entender do que se trata essa ferramenta que nos auxilia a criar documentação para os nossos serviços fornecidos por APIs. O Swagger é um projeto open source que contempla diversas ferramentas para documentação, consumo e visualização de serviços RESTful, entre essas ferramentas, temos o framework para documentação legível de APIs, esse framework implementa a especificação OpenAPI, que é uma linguagem para descrição de contratos de APIs REST. A OpenAPI define um formato JSON com campos padronizados, através de um JSON Schema para que você descreva recursos, modelo de dados, URIs, Content-Types, métodos HTTP aceitos e códigos de respostas. 

O framework do Swagger tem a implementação em diversas linguagens de programação e ao final fornece uma Interface de Usuário, o Swagger UI, para visualização interativa da documentação gerada automaticamente. O projeto ainda possui o Swagger Editor, que é uma ferramenta online, onde é possível escrever com YAML toda a documentação da sua API de forma interativa e sem muito trabalho e a terceira ferramenta no conjunto de projetos é o Swagger Codegen, que cria de forma automática através da sua descrição em YAML, o esqueleto da API com documentação em diversas linguagem de programação, onde ainda é possível gerar o código do cliente que irá consumir o seu serviço. 

O Swagger Editor é muito bom para documentar sua APIs, mas a sua funcionalidade principal é para quando você criar um novo projeto, pois é possível definir toda a estrutura da sua API e gerar o código em sua linguagem favorita para iniciar bem o seu projeto, com a documentação embutida. 

Porém nesse artigo vamos abordar a forma de como documentar uma API já existente, porque é muito comum possuir uma API criada sem documentação, para esse exemplo, vamos utilizar um projeto Spring Boot configurado com o Maven. 

Criando a Documentação na Prática 

Como mencionado, vamos documentar uma API já existente que foi criada com Java, Maven e Spring Boot 2, esse método que será apresentado também pode ser realizado para novos projetos, caso você não queira utilizar o Swagger Editor. 

O primeiro passo é adicionar as dependências do Swagger ao arquivo pom.xml para que o Maven possa baixar as bibliotecas necessárias, para isso basta adicionar ao final do arquivo os seguintes itens (é importante atentar-se que o Swagger para Spring está na versão 2.6.1): 

O próximo passo é inicializar as configurações do Swagger, para isso basta criar uma classe no seu pacote de configuração do Spring e adicionar as notations do Swagger, nesse exemplo o nome da classe é SwaggerConfiguracao e possui o seguinte conteúdo: 

Dois pontos de atenção nesta classe: O primeiro é o basePackage, que indica em qual pacote do seu projeto estão os seus recursos ou controllers, que são as classes que expõem os endpoints da sua API, o segundo é o título (title) e a descrição (description) da sua API, que ao final irá aparecer na sua documentação. 

Agora vamos para a parte da documentação de um dos nosso endpoints, para esse exemplo irei documentar o endpoint que salva um novo usuário no banco de dados, porém por questão de organização do nosso projeto e boas práticas, é preciso tomar as seguintes ações: 

1. Dentro do pacote de recursos da nossa aplicação (RestControllers), vamos criar um subpacote, com o nome swagger, onde iremos criar as nossas interfaces que contém todo o código do Swagger para gerar a documentação. 

2. Na interface vamos colocar todos os nossos métodos da API relacionado ao usuário e depois na classe de recursos, vamos extender (extends) a nossa interface e como os métodos já estão implementados, já teremos a nossa documentação funcionando. 

3. Nessa ação é apenas para atentar-se de que devemos criar os métodos da nossa interface igual os nossos recursos, caso seja projeto existente com parâmetros e retornos iguais, para que não haja problemas. 

A princípio a nossa interface tem o seguinte código: 

No código acima indicamos que o prefixo do nosso recurso são os usuários e a descrição do conjunto de  endpoints. 

A seguir no código abaixo vamos adicionar todas as notations do Swagger que são utilizadas para gerar uma documentação básica do endpoint: 

O Swagger possui uma sintaxe bem fácil de entender, principalmente para quem está acostumado com desenvolvimento Web, porém vamos destacar alguns pontos importantes: 

• ApiOperation: Indica qual é a resposta do endpoint caso sucesso, nesse caso criamos um usuário e retornamos aos dados salvos (UsuarioDTO.class). 
• Authorizations: Indica os métodos de autenticação para acessar sua API, aqui ela pode ter nenhum ou vários e pode assumir alguns valores como basiAuth, BearerAuth, ApiKeyAuth e outros. 
• ApiResponses: Nessa anotação indicamos todos os códigos de retorno da nossa API, seguindo o conceito de RESTful, com a descrição que facilita para o usuário lembrando que isso é o que será exibido na documentação. 

Seguindo esse modelo, agora basta documentar os demais endpoints da sua API, conforme mais um modelo a seguir: 

Ao finalizar a documentação de um endpoint, você poderá conferir como está ficando a sua documentação através do Swagger UI, no momento em que executar o seu projeto, seja local ou em produção, o Swagger irá criar automaticamente uma página HTML, que poderá ser acessada através do link do seu projeto, adicionando o final /swagger-ui.html, dessa forma um exemplo seria http://localhost:8080/api/swagger-ui.html: 

Conclusão 

O Swagger é uma ótima plataforma para gerar documentação para os seus serviços que são oferecidos por API e a sua utilização tem crescido bastante, pois facilita e agiliza a geração de contratos de API para o seu projeto. 

Nesse artigo utilizamos um exemplo escrito em Java, porém para outras linguagens são seguidos os mesmos conceitos e a documentação será gerada da mesma forma, uma dica é utilizar o Swagger Editor para verificar o modelo que é gerado na linguagem em que deseja para o seu projeto.