Validador OpenAPI

Sobre o Validador OpenAPI

A maioria das equipes gera ou escreve à mão um documento OpenAPI e nunca o passa por um linter até que um SDK cliente quebre em produção. Esta ferramenta dá uma primeira revisão rápida e totalmente no navegador: cole seu spec OpenAPI 3.0 ou 3.1 em JSON ou YAML para receber verificação estrutural, resumo endpoint por endpoint e uma lista priorizada de problemas comuns — operationIds ausentes, parâmetros de path não declarados, respostas 401/403 ausentes em endpoints autenticados, operações de escrita sem resposta 400/422 de validação, objetos de resposta sem descrição e request bodies sem exemplos.

Três níveis de rigor para focar no que importa conforme a maturidade da sua API: Básico para rascunhos, Recomendado para revisão de produção e Estrito para specs prontos para SDK. Nenhum spec sai do seu navegador.

Esta ferramenta valida contra o JSON Schema completo do OpenAPI 3.1?

Não totalmente — implementa um subconjunto pragmático focado em problemas que de fato causam falhas de geração de SDK, docs quebrados e brechas de segurança em produção. Verificamos campos raiz obrigatórios (versão openapi, info.title, info.version), declarações de parâmetros de path, caixa dos métodos HTTP, cobertura de códigos de resposta, estrutura de request body em operações de escrita e correlação entre security e respostas. Para validação completa contra o meta-schema oficial, rode CI com Spectral, Redocly CLI ou vacuum após esta revisão de navegador — eles baixam o JSON Schema e aplicam milhares de regras. A ferramenta de navegador é sua revisão diária; o CI é seu portão.

Por que 401 e 403 são marcadas como ausentes se meu endpoint claramente exige autenticação?

Porque clientes, geradores de SDK e exploradores de API precisam de formas explícitas de resposta para tratar erros corretamente. Declarar `security: [{bearerAuth: []}]` informa que autenticação é necessária, mas se você só documenta `200: OK`, o SDK gerado não tem forma tipada para o corpo 401 — então na expiração do token, o cliente lança um erro opaco de parsing em vez de um AuthError tipado. Adicione pelo menos `401: { description: Token inválido ou ausente }` e idealmente um schema com `code` e `message`. Para endpoints baseados em papéis (POST/PUT/DELETE/PATCH) adicione também 403 Forbidden para distinguir 'não autenticado' de 'permissão errada'. Desative a checagem se tratar erros de auth uniformemente em gateway.

Qual a diferença entre OpenAPI 3.0 e 3.1 e este validador suporta ambos?

OpenAPI 3.1 alinha o vocabulário com JSON Schema 2020-12: `nullable: true` é substituído por `type: [string, null]`, `exclusiveMinimum/Maximum` viram números em vez de booleanos, `example` vira `examples` (array), webhooks são de primeira classe e `$ref` pode coexistir com keywords irmãs. O validador detecta 3.0.x ou 3.1.x pelo campo `openapi` e aplica as mesmas checagens estruturais (as regras de lint se sobrepõem muito). Se misturar convenções — como `nullable: true` em spec `openapi: 3.1.0` — a maioria das ferramentas tolera mas a saída do SDK pode surpreender. Para repos multi-versão, fixe uma versão major por projeto.

Por que o parser YAML falha em alguns specs mas a versão JSON funciona?

Enviamos um parser YAML deliberadamente pequeno (sem anchors, sem merge keys `<<`, sem tags `!!type`, sem streams multi-documento `---`) para manter a ferramenta offline e leve. ~95% dos specs reais que testamos parseiam ok, mas specs com muitos anchors YAML (comuns para deduplicar formas de resposta compartilhadas) falharão. Duas soluções: (1) exporte YAML para JSON com `npx js-yaml spec.yaml > spec.json` — expansão de anchors ocorre na conversão; (2) inline anchors manualmente. A mensagem de erro apontará a linha. Para suporte YAML completo, use Spectral ou Redocly CLI no desktop que usam js-yaml completo.

O que significa 'parâmetro de path não declarado' e por que quebra clientes?

Quando seu template de path inclui `{petId}` (ou qualquer `{name}`), cada placeholder deve aparecer na lista `parameters` da operação com `in: path` e `required: true`. Se `{petId}` está na URL mas falta em parameters, geradores como openapi-generator, oapi-codegen, Kiota e openapi-typescript não conseguem produzir um argumento tipado — pulam a operação, emitem um método sem argumentos com `{petId}` literal na URL ou quebram. O validador encontra ambas as direções: parâmetros na URL mas não declarados, e declarados em `parameters` mas ausentes no path. Corrija adicionando declarações faltantes ou removendo obsoletas — a URL é a fonte da verdade.

Cada operação deve ter um operationId único e qual convenção de nomes é melhor?

Sim — geradores usam operationId como nome do método no SDK cliente. Sem ele sintetizam um a partir de método + path, produzindo nomes feios e instáveis como `getPetsPetId`. Convenção: verbo + recurso + qualificador, camelCase: `listPets`, `getPet`, `createPet`, `updatePet`, `deletePet`, `searchPets`, `getPetVaccinations`. Mantenha operationIds globalmente únicos (alguns geradores usam namespace por tag, muitos não). Para listas paginadas prefira `listPets` em vez de `getPets` para sinalizar multiplicidade. Para endpoints em lote use `bulkCreatePets`. O validador marca operationIds ausentes como WARN — corrija antes que qualquer cliente externo consuma seu spec.

Este validador serve para specs OpenAPI gerados por IA (LLMs produzindo definições de API)?

Especialmente adequado. Specs OpenAPI gerados por LLMs (com prompts tipo 'desenhe uma API para X') caem consistentemente nas mesmas armadilhas: descrições de resposta ausentes, parâmetros de path declarados mas não na URL ou vice-versa, métodos minúsculos misturados com maiúsculos, 401 ausente em ops seguras, request bodies com exemplos mas sem schema e respostas de erro esquecidas. Cole a saída do LLM aqui como primeira checagem antes de alimentar um gerador de código ou ferramenta de docs. A combinação validação estrutural + tabela de endpoints + warnings pega cerca de 80% das alucinações de LLM em testes internos com Claude, GPT-4 e Gemini.

Suporta Swagger 2.0 ou só OpenAPI 3.x?

Specs Swagger 2.0 (`swagger: "2.0"` na raiz) são detectados e marcados com recomendação de upgrade — a ferramenta não roda regras de lint neles. Swagger 2.0 entrou em freeze de features em 2014 e o ecossistema (Spectral, Redocly, Stoplight, Postman, AWS API Gateway, Apigee, Kong) favorece OpenAPI 3.x. Converta com `swagger2openapi spec.json` (pacote npm) que lida com 90%+ da migração automaticamente: tipos `body` vão para requestBody, definitions vão para components.schemas e `host`/`basePath`/`schemes` colapsam no array servers. Após converter, cole aqui para linterar o resultado antes de mergear.