OpenAPI e Scalar

OpenAPI e Scalar

Toda API do projeto publica um spec OpenAPI e expõe uma interface de testes interativa com o Scalar API Reference (a UI “powered by Scalar”). Isso é regra, não opcional.

A regra

• Spec OpenAPI descreve todos os endpoints da API (rotas, parâmetros, corpos, respostas, códigos de status).
• O spec é derivado dos schemas Zod. Como o Zod já é obrigatório na validação de toda entrada de API (ver Stack universal), ele é a fonte única: o mesmo schema que valida o request gera o contrato OpenAPI. Não se mantém o spec à mão, em paralelo aos schemas — isso garante que documentação e validação nunca divergem.
• A interface de testes Scalar é servida por uma rota do próprio app (ex.: /reference), permitindo explorar e testar os endpoints direto do navegador.

Padrão de implementação

• Definir os schemas Zod das entradas/saídas de cada endpoint.
• Gerar o documento OpenAPI a partir desses schemas (ex.: via uma biblioteca de zod → openapi).
• Servir o JSON do spec em uma rota (ex.: /openapi.json) e o Scalar API Reference em outra (ex.: /reference), apontando para esse JSON.
• Endpoint novo entra no spec na mesma task que o cria — o spec acompanha a API, não fica para depois.

Relação com testes

O contrato Zod/OpenAPI é também o ponto de partida do desenvolvimento da rota: schema → teste unitário (contra o contrato) → implementação. O fluxo completo está em Testes.

Por que

• Contrato vivo e testável: qualquer pessoa (ou agente) entende e exercita a API sem ler o código.
• Fonte única (Zod): validação, documentação e testes unitários partem do mesmo lugar; tipagem total preservada.
• Onboarding e integração mais rápidos: a UI Scalar substitui coleções manuais de testes.