Aula 04 - Documentação e Mocks 📝
Developer Experience e Contratos
Agenda 📅
- Por que documentar?
- OpenAPI vs Swagger
- Swagger UI e Editor
- O Poder dos Mocks
- Developer Experience (DX)
- Ferramentas de Simulação
1. Documentação é DX 🚀
- Sua API é seu produto.
- Documentar economiza tempo de suporte.
- Facilita a integração com Front/Mobile.
2. OpenAPI (OAS) 📜
- O padrão mundial.
- Arquivo YAML ou JSON descritivo.
- Agnóstico de linguagem.
3. Swagger: O Canivete Suíço 🛠️
- Editor: Escreva e valide o contrato.
- UI: Gere a página visual de testes.
- Codegen: Gere código (client/server) automaticamente.
Swagger UI em Ação
- Permite testar endpoints no próprio navegador.
- Mostra exemplos de JSON de entrada e saída.
- Exibe todos os Status Codes possíveis.
4. O Poder dos Mocks 🎭
- Development in Parallel: Front não espera pelo Back.
- Servidor "Fake" que retorna dados reais.
- Valide a experiência antes da implementação complexa.
5. Developer Experience (DX) 👨💻
Como ser amado por outros devs:
- Nomes de rotas claros.
- Erros descritivos no Body.
- Exemplos de requisição.
- Documentação atualizada (ou gerada pelo código).
6. Ferramentas Recomendadas 🧰
- Swagger Editor: Online ou Local.
- Mockoon: Mock local amigável.
- Prism: Mock via CLI.
- Postman: Collections documentadas.
7. Prática: Editando um YAML 💻
- Desenhando um endpoint
GET /tarefas. - Definindo parâmetros de entrada.
- Criando esquemas de dados.
Desafio: Mock vs Stubs ⚡
Qual a principal vantagem de um Mock Server online (como Postman) em relação a um Mock rodando apenas no computador do desenvolvedor?
Resumo ✅
- OpenAPI é o contrato.
- Swagger UI é a vitrine da sua API.
- Mocks destravam o desenvolvimento da equipe.
- DX é o diferencial de uma boa API.
Próxima Aula: Implementação Backend! 💻
Módulo 2: Manipulação de Dados
- Controllers e Services.
- Repositories e Banco de Dados.
- Mão na massa com código real!