Como documentar facilmente sua API usando o Postman

Como documentar facilmente sua API usando o Postman

As API’s servem para alimentar APPs mobile, sites, chatbots e etc, porém para que os desenvolvedores desses softwares consigam realizar a integração com sucesso é necessário que a API tenha uma boa documentação.

Em geral sempre houve uma certa dificuldade ou retrabalho na hora de realizar essa documentação, porém uma solução rápida e fácil apareceu, usar o postman para fazer isto.

Mas o que é o postman? O Postman é um software utilizado para testar manualmente uma API, com ele você consegue fazer as chamadas Rest para verificar se os seus endpoints estão reagindo corretamente.
Ele não é uma novidade, grande parte dos programadores já utilizavam ele, porém o que é novo é a possibilidade de salvar essas requisições de teste e transforma-las progressivamente na documentação da API.

Então, enquanto você testa e amadurece a sua API você também gera a documentação, que fica online de forma privada ou pública.

Neste artigo eu vou te mostrar como criar a sua primeira documentação elegante e online usando o Postman, vem comigo 😀

O que vamos criar

Vamos construir uma documentação do zero para uma API existente.

Se preferir, você pode utilizar a mesma API deste exemplo acessando este link e seguindo os passos presentes no readme do projeto.

Instalando o Postman

Caso você não tenha o Postman em seu computador acesse este link e faça sua instalação facilmente.

Passo a Passo

Agora vamos começar a criar a nossa documentação, deixe a sua API no ar (a do exemplo ou a que deseja documentar) e siga o passo a passo para aprender como utilizar essa ferramenta incrível 😀

1  – Criando sua Collection

Collection é uma ótima forma de salvar suas requisições para reutilizar posteriormente ou então compartilhá-las. Ela será necessária para a criação da documentação.

1- Abra o Postman e clique em new

2- Selecione a opção Collection e depois preencha os campos Name e Description com os seguintes valores

No campo Name coloque:

Doc Api – OneBitCode

No campo Description coloque:

# Apresentação

Documentação para utilização da Doc Api – Onebitcode.

# Autenticação

Não é preciso utilizar autenticação para fazer requisições a esta API.

# Error Codes

**400 – Bad Request**

Dados enviados de forma incorreta ou fora do padrão

**403 – Forbidden**

Sem autorização suficiente para acessar o recurso desejado

2 – Criando os Folders

A API utilizada neste exemplo conta com objetos do tipo Usuário e Endereço, vamos organizar esses dois tipos em pastas e dentro de cada pasta adicionaremos suas requisições.

1- Para criar uma pasta clique no ícone de configuração da Collection e depois em Add Folder

2- Crie uma pasta com:

Name

Usuário

Description

Está pasta representa um objeto do tipo Usuáro na Doc Api – Onebitcode.

3- Em seguida crie outra pasta com:

Name

Endereço

Description

Está pasta representa um objeto do tipo Endereço que pertence a um usuário do sistema.

3 – Criando as Requisições

Agora vamos adicionar as requisições na nossa documentação.

A – Requisição para listar Usuários

1 – Adicione a requisição do tipo GET (localhost:3000/users) no postman como na imagem a baixo:

2 – Agora click no botão Save que fica do lado do botão Send.

3 –  Na janela que apareceu preencha os campos Request name e  Request description com:

Request name

Listar Usuários

Request description

Exibe uma lista com todos os usuários do sistema.

4 – Selecione corretamente a Collection (Doc API OneBitCode) e depois a pasta (Usuário):

5 – Agora é só mandar Salvar 😎

B – Requisição para cadastrar Usuários

1 – Adicione a requisição do tipo POST (localhost:3000/users) no postman como na imagem a baixo:

2 – Na mesma tela de requisição click em body para adicionar parâmetros, depois click em raw, selecione o tipo JSON (application/json) e coloque o seguinte JSON no campo:

3 – Seu postman deve ficar com o seguinte conteúdo:

4 – Agora click no botão Save que fica do lado do botão Send.

5 – Na janela que apareceu preencha os campos Request name e Request description com:

Request name

Novo Usuário

Request description

Cadastra um novo usuário no sistema

6 – Selecione corretamente a Collection (Doc API OneBitCode) e depois a pasta (Usuário):

7 – Agora é só mandar Salvar 😎

5 – Visualizando a Documentação

1- Para visualizar a documentação que foi gerada até o momento clique em View in Web (Obs: Você precisa se logar no postman para aparecer essa opção):

6 – Requisições com Path Variables

Alguns endpoints como localhost:3000/users/:user_id/address tem um path variável, ou seja, no lugar de :user_id sempre teremos algo diferente, neste exemplo será o id do usuário que queremos deletar o endereço.
Então vamos ver neste exemplo como adicionar esse tipo de endpoint no postman.

1 – Adicione a requisição do tipo DELETE (localhost:3000/users/:user_id/address) no postman como na imagem a baixo:

2 – Depois de adicionar o endereço, adicione os seguintes parâmetros logo a baixo:

4 – Agora click no botão Save que fica do lado do botão Send.

5 – Na janela que apareceu preencha os campos Request name e Request description com:

Request name

Excluir endereço

Request description

Esta requisição é responsável por excluir o endereço de um usuário

6 – Selecione corretamente a Collection (Doc API OneBitCode) e depois a pasta (Usuário):

bdsm dating sites

7 – Agora mande salvar e veja como ficou na documentação 😎

7 – Incluindo Exemplos

Neste tópico você verá que é possível utilizar exemplos para documentar mais de um tipo de resposta para a mesma requisição.

1- Execute novamente a requisição para Excluir Endereço sem alterar o valor de :user_id

A resposta deve ser “error”: “\”Record don’t exists\”” pois o registro não existe mais.

2- Clique no botão de Save para salvar esta nova resposta e depois em Save Example

3- Acesse a documentação e veja que agora você pode alternar entre os exemplos de uma requisição

Resultado Final

Rapidamente conseguimos documentar a nossa API, dê uma olhada no resultado final 😀

Obs: A documentação criada pode ser compartilhada através de um link, para visitar a documentação do exemplo, dating agency over 50.

Conclusão

Através deste artigo foi possível demonstrar que você pode gerar a documentação de sua API ao mesmo tempo em que testa os endpoints com o Postman.

Este processo não toma muito de seu tempo e no final temos como resultado uma documentação bonita e funcional.

A documentação a princípio é privada, mas existe a opção de compartilhá-la em equipe ou então enviá-la para seu domínio.

Se gostou, compartilhe este post com seus amigos e ajude o OneBitCode a continuar trazendo materiais de qualidade para você!

Primeira vez no OneBitCode? Curtiu esse conteúdo?
O OneBitCode tem muito mais para você!

O OneBitCode traz conteúdos de qualidade, e em português, sobre programação com foco em Ruby on Rails e também JavaScript.
Além disso, aqui sempre levamos à você conteúdos valiosos sobre a carreira de programação, dicas sobre currículos, portfólios, perfil profissional, soft skills, enfim, tudo o que você precisa saber para continuar evoluindo como Programador(a)!

Fique por dentro de todos os conteúdos o/

Nossas redes sociais:

📹 • women seeking men in nigeria [Live todas as terças-feiras às 19h)
💻 • reddit top free dating apps
🙂 • https://facebook.com/onebitcode
 📱  • https://instagram.com/one_bit_code
🐦 • https://twitter.com/onebitcode

Nossos cursos:

🥇 • Programador Full Stack Javascript em 8 Semanas
💎 • Curso Completo de Ruby
 ⚙  • Minicurso: API Rails 5 Completo
🐞 • Minicurso de Testes para Ruby on Rails com RSpec

Espero que curta nossos conteúdos e sempre que precisar de ajuda, fala com a gente!
Estamos aqui para você 🙂

Bem-vindo à família OneBitCode o/