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.

 

Ferramentas

  • • Postman v6.4..4

 

 

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 nameRequest 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 nameRequest 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):

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, clique aqui.

 

 

 

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ê!



12 formas de vencer o bloqueio criativo e escrever textos memoráveis (e 6 dicas extras)

Não perca nenhum conteúdo

Receba nosso resumo semanal com os novos posts, cursos, talks e vagas \o/




Você é novo por aqui?

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 outras tecnologias como Angular, Ionic, React, desenvolvimento de Chatbots e etc.

Se você deseja aprender mais, de uma forma natural e dentro de uma comunidade ativa, visite nosso Facebook e nosso Twitter, veja os screencasts e talks no Youtube, alguns acontecimentos no Instagram, ouça os Podcasts e faça parte de nossa Newsletter.

Além disso, também estamos com alguns e-Books muito interessantes para quem deseja se aprimorar como programador e também como freelancer (os e-Books são gratuitos!):

Espero que curta nossos conteúdos e sempre que precisar de ajuda com os tutoriais, fala com a gente! Seja por Facebook ou e-mail, estamos aqui para você 🙂

Bem-vindo à família OneBitCode \o/

novembro 11, 2018

1
Deixe um comentário

avatar
1 Comment threads
0 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
1 Comment authors
fgd Recent comment authors
  Subscribe  
newest oldest most voted
Notify of
fgd
Visitante
fgd

BOOA!

Feito com s2 por OneBitCode
%d blogueiros gostam disto: