Documentando APIs com Postman

Olá a todos, sou desenvolvedor .Net já com uma caminhada de uns 5+ anos é a primeira vez que escrevo aqui e vou procurar fazer mais vezes para agregar conhecimento a comunidade.

Recentemente houve uma necessidade, em determinado projeto na empresa em que atuo, para fazer uma documentação mais amigável que o swagger. Depois de verificar diversas ferramentas, foi em uma que já utilizo há algum tempo em que encontrei o que precisava. Essa ferramenta é o motivo do artigo, onde vou detalhar e exemplificar seu uso para documentação de APIs.

O mais bacana na minha visão é que a medida em que vamos utilizando o postman para testar os endpoints da API em que estamos desenvolvendo, automaticamente já estamos também criando a documentação, pois a cada request que criamos em uma collection, ele também serve como a base documentação, sendo necessário apenas enriquece-lo com mais detalhes e explicações pertinentes ao usuário.

Para exemplificação utilizaremos no processo de documentação uma api publica, a Deck of Cards. Então vamos começar criando uma request para obter um baralho de cartas.

Iremos então no Postman criar uma nova collection com o nome Deck of Cards.

Após criada a collection podemos agora criar a primeira request que irá nos retornar um deck embaralhado com as cartas (Para mais detalhes sobre os parâmetros opcionais da api consulte a documentação).

Ao adicionar a request vamos nomeá-la e configurar alguns parâmetros marcados na imagem abaixo.

Podemos ver que foi informado a rota https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1 e utilizado o verbo http get, no header da requisição foi informado o parâmetro deck_count que por padrão é 1, a documentação no site da api nos dá a informação que o blackjack utiliza geralmente 6 decks ou baralhos (Linguagem ubíqua. Obs.: muito importante na regra de negócio, mas já estamos divagando, é um outro assunto XD). Após realizar a parametrização da requisição e clicarmos no botão send já temos uma resposta da api. Pronto daqui em diante já podemos começar a documenta-la.

Ao clicar na collection é nos apresentado o começo da documentação onde iremos descrever um breve resumo.

Logo abaixo do resumo temos um link que nos direciona para a documentação completa(Adicionei mais alguns endpoints para demonstrar como é exibido a documentação).

Aqui podemos ter uma visão geral de todos os endpoints criados e podemos descrever a funcionalidade de cada um, porém acessando a nossa request, no canto superior direito também temos o acesso a documentação individual daquele endpoint, como veremos a seguir.

No painel lateral que se expande é onde iremos enriquecer a documentação das rotas da api, uma variedade de itens podem ser adicionadas a descrição da rota.

Uma funcionalidade também muito importante e interessante é adicionar um exemplo de uma resposta enviada pela requisição. Para isso iremos realizar uma requisição e no painel response iremos salvar essa resposta como um exemplo que será utilizado para compor a documentação.

Vemos na imagem acima, que abaixo da nossa request foi gerado um arquivo, este é nosso exemplo. É importante na maioria das vezes ocultar informações sensíveis para estar de acordo com a lei LGPD vigente. Também podemos adicionar comentários para facilitar o entendimento.

Agora quando acessamos novamente a documentação completa podemos ver o seguinte resultado.

Podemos ver na imagem acima que nossa rota já está com todas as alterações que fizemos. Por último precisamos publicar nossa documentação para o cliente e é bem simples, basta clicar no botão Publish no canto superior direito.

Então somos direcionados a uma página com algumas configurações para personalizar a documentação, entre elas a url, ambiente, layout, etc.

Por fim basta clicar em publicar no final da página e teremos o link com a documentação online para ser acessada de qualquer lugar.

Acesse aqui para ver o resultado final do exemplo.

Espero que possa ter contribuído para a comunidade da DIO e irei procurar trazer outros artigos de cenários do meu dia-a-dia como desenvolvedor para contribuir como a disseminação de conhecimento. Seu feedback é importante para que eu possa sempre melhorar a qualidade dos artigos XD.