> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiparlance.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Emitter OpenAPI

> @aiparlance/openapi — papel contract, nota 16/33, objetivos pass/partial/fail

# 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](https://github.com/eudameron/aiparlance/blob/main/transpilers/openapi/EMITTER_OBJECTIVES.md) |

Avaliado pelo checklist mestre ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), 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.

## O que produz

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

## ✅ Passou

| 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)             |

## ⚠️ Parcial

| 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) |

## ❌ Ainda falhando (aplicáveis)

| 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](https://github.com/eudameron/aiparlance/blob/main/transpilers/openapi/EMITTER_OBJECTIVES.md).

## Testes

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

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit openapi examples/blog-crud.aip
```

## Relacionado

* [Visão geral dos emitters](/pt/emitters)
* [EMITTER\_OBJECTIVES mestre](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [Primeiros emitters](/pt/first-transpiler)
* [Comece aqui](/pt/getting-started)