Documentação de APIs com Postman

[jeandepaula294]

Documentar a API é uma das etapas mais importantes de um projeto, assim como o desenvolvimento do código e a escrita de testes, sabia?

Existem diversas ferramentas que permitem a documentação das rotas de uma API, e uma delas já é bem famosa na comunidade de desenvolvedores, o Postman. Ela possui como principal propósito facilitar a realização de requisições, mas um de seus recursos é transformar as suas collections de requisições na documentação da sua API. Legal, né?

Para te mostrar como é simples, vou criar a documentação de uma API! Para agilizar, vou usar como base uma API simples de cadastro de usuários que eu desenvolvi com Node.js e Express, ela está lá no meu github.

Ah, você pode usar o Postman para documentar qualquer API REST, independentemente da linguagem de programação, beleza?

 

1. Montar collection de requisições

Se você já utilizou o Postman alguma vez, deve saber que ele permite salvar as requisições das rotas da sua API.

No caso da API que eu fiz, ela possui 5 rotas e todas seguem alguns princípios da padronização da arquitetura REST, como utilizar os métodos e status HTTP corretamente e identificar o recurso nas rotas da requisição, por exemplo.

Se você não lembra muito bem sobre os conceitos de uma API REST, tem esse meu artigo lá no blog da casa do desenvolvedor: REST APIs: Introdução às Interfaces de Programação

Essa minha API de exemplo possui somente cinco rotas para manipulação de usuários:

• [POST]/users - para criar um usuário
• [GET]/users - para listar TODOS os usuários
• [GET]/users/:id - para listar um usuário pelo seu id
• [PUT]/users/:id - para atualizar um usuário pelo seu id
• [DELETE]/users/:id - para atualizar um usuário pelo seu id

No meu Postman, eu deixei montado todas as requisições da API:

 

2. Realizar requisições e salvar respostas

Com a sua collection montada, você já pode começar a fazer as requisições para a sua API. Para facilitar a documentação, podemos utilizar as próprias respostas que a API nós retorna, olha só:

Ao fazer a requisição, aparece esse botão que nos permite salvar a resposta dessa rota como um exemplo. Nessa etapa, é legal você simular todos os retornos possíveis da sua API. Assim, todas as suas respostas vão ficar salvas abaixo de cada uma das rotas da sua API, dessa forma:

Eu fiz isso para cada uma das rotas da API e no final ficou assim:

 

3. Gerar documentação automaticamente

Aqui é que a mágica acontece. Ao clicar nos três pontos da sua collection e abrir as opções, aparecerá a opção para você gerar a documentação da sua API, com base nas requisições e respostas dela.

Na documentação aparecerá todas as suas rotas e os retornos de cada exemplo que você salvou, incluindo o corpo, status e headers das respostas da API.

Você também pode adicionar a descrição de cada rota e uma explicação sobre os parâmetros que podem ser enviados em cada uma das rotas, para facilitar ainda mais para quem for ler a sua documentação.

 

4. Customizar visual da documentação

Uma das partes mais legais que o Postman permite é personalizar o visual da documentação, para deixar ela com a cara do seu projeto.

No canto superior direito do seu Postman, aparecerá um botão que permite você customizar a documentação antes de publicar:

Ao clicar nele, irá abrir uma página que permite você customizar o visual de sua documentação e deixar ela com as cores da identidade visual do seu projeto ou até mesmo adicionar um domínio personalizado, por exemplo. Bacana, né?

 

5. Publicar documentação na WEB

Por fim, agora é só publicar a sua documentação e o Postman disponibilizará para você uma URL para compartilhar com todo mundo!

Olha aí como ficou o resultado final da documentação:

https://documenter.getpostman.com/view/25996150/2s9YkuXxXU

 

6. Conclusão

O Postman é somente uma das inúmeras ferramentas que permitem a criação de documentações de API, além de possibilitar a customização do seu visual e a publicação na WEB, independentemente da linguagem de programação.

Só fica atento para não colocar dados reais nos exemplos que você disponibilizar na sua documentação, principalmente por questões de segurança, ok?

 

E você, conhece mais alguma ferramenta que acha muito legal? Compartilha com a gente aqui na casa do desenvolvedor, vamos adorar ler!

 

Editado Dezembro 28, 2023 por jeandepaula294
Atualização