Documentação de API não é luxo — é necessidade. Especialmente quando estamos construindo um sistema real, como o nosso Mini CRM Lead Tracker.
Para garantir que o sistema seja sustentável, optamos por usar o padrão Swagger para documentar a API RESTful do CRM.
O que é Swagger?
Swagger é um conjunto de ferramentas que usa o padrão OpenAPI Specification para definir, visualizar e interagir com APIs RESTful de maneira padronizada e automática.
Por que estamos usando Swagger no Mini CRM?
- 📚 Documentação automatizada e padronizada dos endpoints de leads.
- 🔍 Facilidade para o front-end Vue.js consumir a API.
- 🛡️ Melhora a manutenção e escalabilidade do CRM.
- 🤝 Facilita a integração com futuras automações em Python e exportações para Sheets.
Exemplo real de anotação (Laravel PHPDoc)
/**
* @OA\Post(
* path="/api/v1/leads",
* summary="Cria um novo lead",
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* required={"nome", "email"},
* @OA\Property(property="nome", type="string"),
* @OA\Property(property="email", type="string")
* )
* ),
* @OA\Response(
* response=201,
* description="Lead criado com sucesso"
* )
* )
*/
Conclusão
Swagger nos permite manter o nosso Mini CRM organizado, claro e fácil de integrar — o que é fundamental para qualquer sistema sério que queremos que dure e evolua.
“Se não está documentado, é como se não existisse.”
Você já documenta suas APIs assim? Ou ainda deixa tudo na mão de Deus? 😂