Como documentar APIs de um Mini CRM usando Swagger

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? 😂