Documentando APIs Rest - Swagger, OpenApi e Insomnia

Acredito que seja "batido" dizer que documentação é uma boa prática e deveria ser um pré-requisito nos projetos(as vezes até é, só não é implementado).

Pense em outras pessoas que estão trabalhando com você (ou que irão), o Frotend/Mobile dev com duvida sobre o que enviar e quais os possíveis retornos ou mesmo liberar acesso externo para algum recurso para que outra pessoa consuma-os. Todos esses casos vão ser solucionados facilmente com uma documentação bem escrita. Neste post, vamos focar na documentação dos recursos e endpoints de uma aplicação simples, porém que vai cobrir boa parte dos casos.

✍🏼Formas de documentar uma api.

Aqui vou focar em dois modos de documentarmos uma api, não são os únicos obviamente, porém são os que eu tenho mais intimidade e portanto decidir abordar aqui, também são os mais comuns.
O primeiro é utilizando algum cliente Rest, ou um programa que faça as requisições para os nossos endpoints e nos mostre o retorno, dentre os mais famosos temos o Postman e Insomnia.
O segundo é utilizando o Swagger e seguindo as especificações do OpenApi, uma forma excelente e que engloba boa parte das soluções no quesito documentação.

🤹🏽‍♀️Documentando com clientes Rest (Insomnia, Postman...)

Uma maneira mais simples para se documentar uma api é com um cliente rest, nele você consegue criar requisições (sejam elas; post, get, put ou delete) passando a url, informando headers, body, tokens e tudo mais. Dessa forma, o programa irá fazer a requisição com os dados preenchidos, é muito comum a utilização de um programa desse durante o desenvolvimento da api e todo esse conteúdo que você cria, se organizado de forma correta, pode ser utilizado como uma documentação (o ideal é uma documentação nas especificações do OpenApi, sem dúvidas, porém um arquivo desse é um norte muito bom pra quem não tinha nenhum), basta exportar o arquivo como json ou yml e passar para outro dev. Acredito que seja uma solução rápida e que funcione ali dentro  do seu time, talvez não seja uma boa forma de expor para um terceiro como arquivo de consulta.

Também é possível "converter" um arquivo do Insomnia para um arquivo nas especificações do OpenApi para que o Swagger(já vamos falar dele) possa ler, aqui por exemplo tem um bem interessante.

⭐️Documentando api com as especificações do OpenApi (usando Swagger).

Acima eu falei sobre a especificação OpenApi, agora eu vou explicar o que é essa especificação. Originalmente era chamada de Swagger specification, foi renomeada para OpenApi specification em meados de 2016 após a SmartBear criar uma nova organização com o suporte da Linux Foundation. Em poucas palavras, essa especificação é um conjunto de especificações para descrever, produzir, consumir e visualizar apis rest/restfull.

Se OpenApi é a especificação, as "normas" de como fazer a nossa documentação, o Swagger é a ferramenta que usamos para implementar essa especificação. Inclusive é possível executar requisições dentro da sua própria documentação com os dados que você documentou. Com o Swagger temos uma gama de ferramentas, algumas open source, grátis e pagas que podemos usar no desenvolvimento da nossa doc. Algumas ferramentas do Swagger são;

Swagger Editor: Utilizado para editar o arquivo Yaml com as especificações OpenApi da sua documentação e que permite a visualização em tempo real, direto no navegador.

Swagger UI: Um conjunto com Html, css e javascript para servir á sua documentação dinamicamente (permitindo fazer requisições dentro da própria doc).

Swagger Inspector: Uma alternativa ao Postman e Insomnia, um cliente rest direto do navegador com a possibilidade de exportar os dados no formato do OpenApi para utilizar no Swagger Editor posteriormente por exemplo.

👨🏽‍💻Colocando a mão na massa

Para esse exemplo, vou utilizar uma aplicação em Nodejs, porem não se apegue a linguagem ou o framework que estou usando aqui, tudo que vimos até aqui pode ser utilizado em qualquer outro ambiente.

Começando pelo Insomnia;

Essa é a tela inicial do Insomnia, é bem simples, clicando no nome Insomnia[1] (onde tem uma seta do lado direito) podemos alterar ou criar um novo Workspace e alterar as configurações (como tema, plugins, exportar o arquivo etc). Em "No Environment"[2] é o local em que podemos fazer configurações do nosso ambiente (caso esteja familiarizado com os arquivos .env, encare como isso), basicamente um arquivo json onde você pode definir coisas como baseUrl, token e afins de acordo o ambiente que você deseja (produção e local por exemplo). Onde temos o ícone de "+" é onde podemos adicionar uma nova request ou criar uma pasta(para organizarmos o projeto).

Tendo essa pequena intro, vamos começar criando um novo Workspace, logo após criar algumas pastas, eu vou criar as seguintes pastas; Auth, User, Photos e News, e dentro delas vou criar as requisições, começando por Auth;

Dentro da pasta Auth eu criei uma nova requisição, dei o nome de "Login" e coloquei o método "Post" nela. Na url perceba que eu chamei uma "variável" do meu arquivo de ambiente e concatenei com minha rota. O body eu mudei para JSON e coloquei um objeto Json com os campos que eu preciso para fazer login na minha aplicação. Por ultimo, na parte de baixo temos o retorno da requisição, temos diversas informações como o código de status do retorno, o tempo e tamanho da requisição e claro, o retorno, que no meu caso foi o tipo do token, o token e o refreshToken (null).

Seguindo essa mesma logica, criei outras request com outros métodos para o restante das minhas pastas, e o resultado foi esse:

Então aqui temos um arquivo com todos os endpoints da minha aplicação e o que eles esperam e a possibilidade de testar o retorno, agora basta irmos no nosso workspace e exportar todo esse arquivo;

Podemos escolher quais pastas e requisições queremos exportar também, após escolher basta clicarmos em "Export";

Em seguida escolha o formato que deseja exportar (json ou yml) e salve, basta passar para outra pessoa e pedir pra que ela importe o arquivo no Insomnia e pronto, toda a doc estará lá! Lembre-se sempre de atualizar esse arquivo, de acordo com o a sua api.

Documentando com o Swagger

Utilizarei a mesma api para documentar no Swagger, e aqui temos duas possibilidades, a primeira é utilizarmos alguma lib para que essa doc seja "automática" e que ela fique dentro do nosso projeto, junto ao código (ou separado em um arquivo, mas no mesmo nível do arquivo a ser documentado, é como eu prefiro),  e a segunda seria realizar a documentação totalmente manual. Como a forma "automática" depende da linguagem e framework que você utiliza, eu não vou aprofundar nela, apenas mostrar alguns exemplos em algumas linguagens e sugerir algumas libs. O funcionamento no geral é bem parecido entre as linguagens e frameworks;

• Nodejs Express - express-swagger-generator

• Laravel Php - L5-Swagger

• Java Spring Boot - Springfox Swagger UI

(fonte: https://www.treinaweb.com.br/blog/documentando-uma-api-spring-boot-com-o-swagger/)

Como podemos perceber, são bem parecidos apesar da mudança de linguagens, usamos comentários/anotações para descrever os nossos resources, também é possível fazer isso com as models.

🏋🏽Fazendo a documentação de forma manual no Swagger

Agora vamos a criação da documentação "por fora do projeto". Em alguns casos você pode optar por não encher o código da sua aplicação de anotações ou criar arquivos com essas informações no projeto e preferir criar a documentação totalmente separada, vamos fazer isso agora. Vamos até o site do Swagger Editor;

Ao entrar já temos um exemplo carregado com uma api demo de um petshop, é uma ótima ideia analisar toda essa doc demo por que ela aborda praticamente tudo que você precisa para criar a sua, e não é má ideia usa-la como base.

Na barra de títulos temos algumas ferramentas que facilitam bastante as coisas pra nós, em file podemos importar uma url (você pode criar uma conta no Swagger e salvar sua documentação, podendo enviar o link sem precisar servir esse arquivo você mesmo), importar arquivo, salvar e converter. Temos também a função "Generate Server" que gera uma api para você na linguagem/framework que você escolher (aqui falamos de magia negra, com toda certeza) e em "Generate Client" temos a opção que vai exportar um cliente para servir a nossa doc, caso você queira hospedar ela em seu próprio servidor, intranet, container docker etc.

A estrutura do arquivo Yml

Como podemos observar, o nosso arquivo yml é o onde colocamos toda a informação da nossa aplicação, os campos são bem auto-explicativos então dispensa uma descrição campo a campo. Temos alguns campos que são obrigatórios e outros que não, para saber quais são obrigatórios, os formatos e quais campos você tem disponíveis, basta consultar a documentação da OpenApi e ver os schemas.

Aqui podemos perceber algumas coisas interessantes, onde temos "tags" são os nossos "módulos" da aplicação, e em paths temos os endpoints para cada tag, lembrando que precisamos declarar dentro do path o nome da tag, para que fique referenciado qual path pertence a qual tag. No caso da minha api, ficaria da seguinte forma:

Embora a doc do OpenApi explique bem, eu vou dar uma revisada sobre o que fiz aqui. Em "tags" eu criei o nome do meu "modulo" e dei uma descrição a ele, esse name usamos para referenciar em outros lugares da aplicação, como utilizei no paths, na linha 30, onde eu disse que aquele path pertence a a tag/modulo "auth". Dentro do path eu vou definir os endpoints, dentro do endpoint eu posso definir o/os método(s) (um endpoint pode ter vários ou apenas um método) e dentro do método eu coloco a tag, um sumario (descrição curta), uma descrição mais longa, um id e mais algumas informações sobre o tipos que a aplicação aceita e devolve.

Mais abaixou eu tenho os parâmetros que minha requisição possui, nesse caso adicionei apenas o body, coloquei a descrição nele e marquei como requerido, em schema eu defino o que vai no body, então fiz uma referencia a um objeto(mais abaixo no arquivo). Em responses vamos colocar todas as possíveis respostas que esse endpoint pode ter, caso seja não autorizado, usuário invalido, criado com sucesso e etc.

Aqui temos nossas definições, sendo esta a de auth que usei mais acima, nada muito complexo também, apenas disse o tipo do objeto, o que é requerido e as propriedades com o tipo e exemplo.

O Swagger Editor também faz uma verificação de erros no nosso arquivo, facilitando ainda mais a criação da nossa documentação. 

Então vou finalizando esse post por aqui, vou deixar o arquivo yml nesse gist aqui caso você queira dar uma olhada nele completo. Espero que você tenha gostado e que eu tenha conseguido passar pelo menos um pouquinho do conhecimento sobre documentação de api para você e espero de verdade que isso te ajude! Abraços e até a próxima!

💁🏽‍♀️Menções honrosas:

Vale aqui citar o Api Blueprint que utilizar markdown para documentar a api, também temos o Raml como alternativa. Embora não abordado (por ser muito parecido com Insomnia) o Postman (assim como o Insomnia) tem outros tools, incluindo para design de api, como o Swagger Editor (que também pode ser baixado).

Muito obrigado a Victoria Trindade, que me ajudou de mais nesse post!