OpenAPI: importar e exportar

O produto importa um documento OpenAPI 3.0 ou Swagger 2.0 para criar a API, o backend e as rotas, e exporta o rascunho atual como OpenAPI 3.0.

Importar

POST /v1/apis/import com o documento no corpo (application/json ou application/yaml).

curl -sS -X POST "$BASE/v1/apis/import?name=Pedidos&dry_run=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/yaml' \
  --data-binary @openapi.yaml

O que é criado

1. A API, com nome vindo de ?name= (ou de info.title).
2. O backend, a partir de servers[0].url — se ele passar na política de destino. Se não passar, nenhuma rota é criada e o motivo aparece em pending_configurations.
3. Uma rota por operação (caminho + método).
4. As rotas resultantes aparecem em routes com method, path e route_id.

dry_run

Com ?dry_run=true, a resposta é 200 e nada é gravado: você vê o relatório antes de decidir. Sem dry_run, a resposta é 201.

Relatório

{
  "dry_run": true,
  "api_name": "Pedidos",
  "operations_imported": 12,
  "routes_created": 0,
  "pending_configurations": ["backend_not_allowed:private_address"],
  "unsupported_extensions": ["x-amazon-apigateway-integration", "x-ms-paths"],
  "routes": [
    {"method": "GET", "path": "/pedidos/{id}", "route_id": "0192f3a4-…"}
  ],
  "parser_messages": []
}

Se pending_configurations vier preenchido, a API foi criada sem as rotas — porque sem backend válido não há para onde encaminhar. Corrija o destino e importe de novo, ou crie as rotas manualmente.

O que não é suportado

Item	Comportamento
$ref externo	não é resolvido: a importação lê apenas o documento enviado
$ref interno	também não é resolvido: o conteúdo referenciado não é materializado
x-amazon-apigateway-*	listadas em unsupported_extensions; nunca executadas
x-ms-* (Azure)	idem
securitySchemes e security	não configuram a autenticação do produto. A API nasce com o modo padrão (API_KEY) e você ajusta depois
Servidores múltiplos	só servers[0].url é usado
Parâmetros de query e header como contrato	a rota é criada por caminho + método; validação de parâmetros é do seu backend
webhooks, callbacks, links	ignorados

O parse é feito sem resolver referências externas — decisão de segurança: nenhum $ref de um documento enviado pelo cliente vira requisição do control plane.

Limites do documento

Limite	Padrão	O que acontece ao exceder
Tamanho do documento	1 MiB	413 payload_too_large
Aliases e âncoras YAML para coleções	50	422 invalid_openapi com reason = yaml_aliases_exceeded
Profundidade de aninhamento	128	422 com reason = yaml_depth_exceeded
Nós após expandir os aliases	500 000	422 com reason = yaml_expansion_exceeded
Âncora que contém o próprio alias	—	422 com reason = yaml_recursive_alias
Prazo do parse	5 s	422 com reason = parse_timeout
Imports simultâneos	2	429 too_many_requests com reason = openapi_parser_busy

O motivo de existir: um YAML de poucos bytes com âncoras aninhadas ("billion laughs") faria o parser expandir para bilhões de nós e derrubar o processo. O produto lê o grafo sem expandir, mede o tamanho que a expansão produziria e recusa antes de o parser ver o documento. Documento que começa com { é lido como JSON e não passa por essa pré-leitura (JSON não tem âncoras).

Depois de importar

1. Confira as rotas criadas (GET /v1/apis/{apiId}/routes).
2. Ajuste o que o documento não expressa: política de autenticação, CORS, limite de taxa, timeouts e tls_verify.
3. Publique. A importação não publica.

Exportar

GET /v1/apis/{apiId}/openapi devolve o rascunho em OpenAPI 3.0 (YAML), com os paths e métodos das rotas atuais.

curl -sS "$BASE/v1/apis/$API_ID/openapi" \
  -H "Authorization: Bearer $TOKEN" -o api-exportada.yaml

O documento exportado é um ponto de partida, não uma cópia fiel de tudo:

• traz caminhos, métodos e o esquema básico;
• não traz políticas de segurança do produto, CORS ou limites configurados no gateway;
• não traz o endereço público no formato que o importador usa como backend (o endereço padrão não é um backend válido e seria recusado pela política de destino, corretamente).

Ou seja: exportar e reimportar em outra organização não é um caminho de cópia de configuração. Para isso, use as revisões e a API administrativa.

Erros

Resposta	Código	Causa
422	invalid_openapi	documento que não é OpenAPI ou Swagger válido, ou recusado pelos limites de YAML (o reason diz qual)
413	payload_too_large	documento acima do teto
429	too_many_requests (openapi_parser_busy)	imports simultâneos demais
401 ou 403	—	sem credencial ou sem permissão de escrita
201 com pending_configurations	—	documento válido, backend não permitido

Próximos passos

• Rotas: as regras que a importação precisa respeitar.
• Backends: por que um destino pode ser recusado.
• Publicação: o passo que a importação não faz.