09-Postman e Documentação

Materiais desta aula

SlidesSlide AtividadesExercício/Atividade StockAPI.postman_collection.jsonOutro StockAPI_Local.postman_environment.jsonOutro

09 — Postman e Documentação

Sumário

O problema de hoje
Collection e pastas
Variáveis e ambiente
Token automático
Autenticação herdada
Exemplos salvos e descrições
OpenAPI
Gerando e lendo a especificação
Guardando no projeto

1. O problema de hoje

Até aqui, os testes da StockAPI foram feitos com requests soltas no Postman:

URL repetida: http://localhost:3000/api digitado em cada request. Mudou a porta? Edite uma por uma.
Token na mão: fazer login, copiar o token, colar no header. Ele expira, e tudo de novo.
Sem documentação: quais rotas existem? O que enviar? O que volta? Só quem escreveu o código sabe.

Hoje: uma Collection organizada, que vira a documentação da API.

2. Collection e pastas

Uma Collection é uma pasta de requests. Dentro dela, pastas agrupam as requests por recurso:

StockAPI
├─ Auth
│  ├─ Registrar usuário
│  └─ Login
├─ Produtos
│  ├─ Criar produto
│  ├─ Listar produtos
│  └─ ... (5 requests)
└─ Categorias
   └─ ... (5 requests)

Collections ▸ + ▸ nome: StockAPI
Add folder: Auth, Produtos, Categorias
Arraste as requests para as pastas
Nome no padrão verbo + recurso: "Criar produto", não "New Request"

3. Variáveis e ambiente

Uma variável é escrita assim: {{nome}}. Escreve-se uma vez e usa-se em todo lugar. O ambiente é o conjunto de variáveis de um contexto (hoje, o seu computador).

O ambiente `StockAPI Local`

Variável	Valor	Quem preenche
`baseUrl`	`http://localhost:3000/api`	Você, uma vez
`token`	(vazio)	O login, sozinho

As mesmas requests com valores diferentes: mais tarde o ambiente pode ser o servidor da escola, e troca-se o ambiente, não as requests.

Antes e depois

http://localhost:3000/api/produtos
http://localhost:3000/api/produtos/1

{{baseUrl}}/produtos
{{baseUrl}}/produtos/1

Selecione o ambiente no canto superior direito. Maiúsculas importam: {{baseURL}} não é {{baseUrl}}.

4. Token automático

No request Login, aba Scripts ▸ Post-response (em versões antigas, aba Tests):

pm.environment.set(
  "token",
  pm.response.json().token
);

pm.response.json() — o corpo da resposta já convertido em objeto: { token: "…" }.
pm.environment.set(nome, valor) — grava (ou atualiza) a variável no ambiente selecionado.

5. Autenticação herdada

Em vez de configurar o token em cada request, configure uma vez na Collection:

Collection ▸ Authorization
  Auth Type   Bearer Token
  Token       {{token}}

Inherit auth from parent (padrão): usa o token da Collection. Vale para Produtos e Categorias.
No Auth: Registrar usuário e Login, porque ainda não existe token para enviar.

Resultado: DELETE /produtos/:id envia Authorization: Bearer … sozinho.

6. Exemplos salvos e descrições

Enviar a request e ver a resposta da API.
Na resposta: Save Response ▸ Save as example.
Um exemplo por situação: "Criado (201)", "Dados inválidos (400)", "Não encontrado (404)".
Descrever a request em uma frase: o que faz e o que exige.

Sem exemplo e sem descrição, a documentação sai vazia.

7. OpenAPI

OpenAPI é um padrão para descrever uma API em um arquivo de texto (YAML ou JSON):

Contrato da API: descreve as rotas, o que cada uma recebe e o que devolve.
Um padrão: ferramentas diferentes leem o mesmo arquivo (documentação, testes, geração de código).
Texto: cabe no Git, junto com o código da API.

Nesta disciplina usamos OpenAPI 3.0.

Como é uma especificação (exemplo reduzido)

openapi: 3.0.0
info:
  title: StockAPI
  version: 1.0.0
paths:
  /produtos:
    get:
      summary: Listar produtos
      responses:
        '200':
          description: OK

O Postman gera uma versão mais completa.

O que da Collection vai para a especificação

Na Collection	Na especificação
Método e URL da request	Rota (`path`) e operação (`get`, `post`…)
Body de exemplo da request	Corpo da requisição (`requestBody`)
Exemplos salvos	Respostas (`responses`): 200, 201, 400…
Descrição da request	Descrição da operação

O Postman só leva para a especificação o que você escreveu na Collection.

8. Gerando e lendo a especificação

Collection ▸ ⋯ ▸ More ▸ Generate specification
Nome: StockAPI; formato: YAML
Generate Specification; depois, abrir em Specs, na barra lateral
Mudou a Collection? Overview ▸ Sync specification

Cada Collection gera uma especificação por vez.

Procure na sua especificação

O que procurar	O que mostra
`openapi: 3.0.x`	A versão do padrão, na primeira linha
`paths`	Uma entrada por rota: `/produtos`, `/categorias`…
`get`, `post`, `put`, `delete`	Os métodos de cada rota
`responses`	Os códigos dos exemplos que você salvou

Faltou algo? Volte à Collection, complete e sincronize.

9. Guardando no projeto

stockapi/
├─ docs/
│  └─ openapi.yaml
├─ postman/
│  ├─ StockAPI.postman_collection.json
│  └─ StockAPI_Local.postman_environment.json

Collection e ambiente: ⋯ ▸ Export
Colega: Import ▸ arraste os arquivos

Antes do commit: abra o JSON do ambiente. Se o token estiver lá, apague o valor. Token nunca vai para o Git.

Atividade

Documentando Categorias (em dupla): pasta Categorias com 5 requests, descrições e exemplos (200, 400, 404, 401), geração e leitura da especificação, arquivos no projeto e três perguntas. Ver E09_atividade.docx.

Arquivos de referência

StockAPI.postman_collection.json — Collection completa (Auth, Produtos, Categorias): auth Bearer herdada, script do token, descrições e 20 exemplos salvos.
StockAPI_Local.postman_environment.json — ambiente com baseUrl e token.

Para a próxima aula

Testando a API no Postman. pm.test, Runner e testes funcionais da StockAPI, sobre a Collection de hoje.

Douglas Legramante