Emitter OpenAPI


Pacote	`@aiparlance/openapi`
CLI	`aip emit openapi`
Papel	`contract`
Nota	16/33 (48%)
Nível	Prévia útil
Ficha de maturidade	transpilers/openapi/EMITTER_OBJECTIVES.md

Avaliado pelo checklist mestre (55 IDs, v2 · 2026-08-06).

Resumo

✅ Passou	⚠️ Parcial	❌ Falhou	➖ N/A
16	3	14	22

Itens N/A estão fora do papel contract e não entram no denominador da nota.

OpenAPI 3.0.3 JSON: schemas, paths CRUD, api.prefix, schemes de auth.

ID	Objetivo
`A1`	Gerar as estruturas da entidade (types / structs / schemas / tables) a partir de `entity`
`A2`	Gerar tipos de entrada para criação (`EntityCreate` ou equivalente)
`A3`	Gerar tipos de entrada para atualização (`EntityUpdate` ou equivalente)
`A4`	Gerar enums / variantes restritas a partir de `enum(…)`
`A5`	Gerar `belongs_to` como FKs ou referências
`A6`	Gerar a chave primária implícita `id`
`A7`	Gerar `timestamps` (`created_at` / `updated_at`)
`A8`	Gerar campo/coluna `soft_delete` (`deleted_at`)
`B1`	Respeitar `required` / `optional`
`D1`	CRUD completo para entidades listadas em `crud` (list/create/get/update/delete)
`D2`	Respeitar `api.prefix`
`D7`	Respeitar `api.format` (ex.: JSON)
`E1`	Esquema de autenticação a partir de `app.auth` (`jwt` / `api_key` / `session` / `oauth`)
`H3`	Golden / CI para `minimal.aip` (ou equivalente no alvo)
`H4`	O emit funciona nos examples full-tier correspondentes sem crash
`H5`	Nomenclatura alinhada à documentação (tabelas no plural, `*_id`, snake_case)

ID	Objetivo
`B2`	Respeitar `unique`
`B4`	Mapear tipos semânticos (`email`, `phone`, …) de forma distinta
`E2`	Integrar autenticação na API (requisitos de segurança ou middleware)

ID	Objetivo
`A9`	Semântica de soft-delete (leituras padrão filtram linhas deletadas)
`B3`	Aplicar `validation { }` além de marcar campos como obrigatórios
`D3`	Respeitar `api.cors` (config ou middleware)
`D4`	Respeitar `api.rate_limit` (config ou aplicação)
`D5`	Paginação e/ou filter/sort em list
`D6`	Respostas de erro tipadas (4xx/5xx + shape estável do body)
`E3`	Refletir `policy` create/read/update/delete
`E4`	Predicados: `public`, `authenticated`, `role(…)`
`E5`	Predicados: `owner` / `owner_or_manager(…)`
`E6`	Caminhos consistentes de negação 401/403 (runtime ou contrato documenta ambos)
`H1`	Documentação legível de API / domínio
`H2`	Fixtures ou scaffolds de testes automatizados
`I1`	Client / SDK tipado da API (ou codegen a partir do contrato)
`I2`	História de paridade contrato↔runtime (paths/types compartilhados ou check de CI)

Ficha de maturidade completa (incluindo ➖ N/A): transpilers/openapi/EMITTER_OBJECTIVES.md.

Golden minimal.openapi.json + CI. Prefix OpenAPI assertado em exemplos crm/blog.

npm test
node packages/cli/dist/cli.js emit openapi examples/blog-crud.aip