Documentando APIs e testando com Postman, Thunder Client e scripts.
Outros devs precisam entender como usar a API sem ler o codigo fonte.
Integradores externos dependem da documentacao para conectar seus sistemas.
Documentar ajuda a encontrar inconsistencias e pensar melhor na API.
# API de Produtos
## Autenticacao
Todas as rotas de escrita precisam do header:
Authorization: Bearer <token>
## Endpoints
### POST /api/auth/registrar
Body: { "nome": "string", "email": "string", "senha": "string" }
Resposta: 201 { "token": "..." }
### GET /api/produtos
Query params: ?categoria=X&pagina=1&limite=10&ordem=preco
Resposta: 200 { "produtos": [...], "total": 47, "pagina": 1, "paginas": 5 }
### POST /api/produtos (requer auth)
Body: { "nome": "string", "preco": number, "categoria": "enum" }
Resposta: 201 { produto criado }
### PUT /api/produtos/:id (requer auth)
Resposta: 200 { produto atualizado }
### DELETE /api/produtos/:id (requer auth)
Resposta: 204 (sem body)
$ npm install swagger-ui-express swagger-jsdoc
// No index.js
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
const specs = swaggerJsdoc({
definition: {
openapi: '3.0.0',
info: {
title: 'API Produtos',
version: '1.0.0'
}
},
apis: ['./routes/*.js']
});
app.use('/docs',
swaggerUi.serve,
swaggerUi.setup(specs)
);
/**
* @swagger
* /api/produtos:
* get:
* summary: Lista todos os produtos
* tags: [Produtos]
* parameters:
* - in: query
* name: categoria
* schema:
* type: string
* description: Filtrar por categoria
* - in: query
* name: pagina
* schema:
* type: integer
* default: 1
* responses:
* 200:
* description: Lista de produtos
* post:
* summary: Cria um novo produto
* tags: [Produtos]
* security:
* - bearerAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required: [nome, preco, categoria]
* properties:
* nome:
* type: string
* preco:
* type: number
* categoria:
* type: string
* enum: [Eletronicos, Roupas, Alimentos, Livros, Outros]
* responses:
* 201:
* description: Produto criado
* 401:
* description: Nao autorizado
*/
API Produtos/
Auth/
POST Registrar
POST Login
Produtos/
GET Listar todos
GET Buscar por ID
POST Criar produto
PUT Atualizar produto
DELETE Remover produto
// Definir variaveis
base_url = http://localhost:3000
token = (preenchido apos login)
// Usar nas requests
URL: {{base_url}}/api/produtos
Auth: Bearer {{token}}
// Script pos-login (Postman)
const data = pm.response.json();
pm.environment.set(
"token", data.token
);
// Na aba "Tests" do Postman
pm.test("Status 200", () => {
pm.response.to.have.status(200);
});
pm.test("Retorna array", () => {
const data = pm.response.json();
pm.expect(data.produtos)
.to.be.an('array');
});
pm.test("Tem paginacao", () => {
const data = pm.response.json();
pm.expect(data)
.to.have.property('total');
pm.expect(data)
.to.have.property('paginas');
});
swagger-ui-express e swagger-jsdoc/docs e veja a documentacao interativaIntroducao a seguranca web (OWASP, XSS, CSRF).