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, ou envie seu arquivo openapi.yaml / openapi.json, 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 (incluindo parâmetros compartilhados no nível do path item), 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.

A ferramenta também percorre cada $ref do documento e marca como erro as referências locais não resolvidas (um #/components/schemas/Foo pendurado) além das refs externas/remotas que não consegue baixar offline — a maior causa de falhas em geradores de código e operações descartadas silenciosamente. 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.

Como valido um arquivo OpenAPI ou Swagger online?

Três passos, tudo no seu navegador. (1) Cole seu documento OpenAPI 3.0 ou 3.1 na caixa como JSON ou YAML, ou envie seu arquivo openapi.yaml, openapi.yml ou openapi.json com o botão de arquivo acima da área de texto. (2) Escolha um nível de rigor — Básico para rascunhos, Recomendado para revisão de produção, Estrito para specs prontos para SDK — e ative as verificações de respostas auth e exemplos como preferir. (3) Clique em Validar spec. Você obtém na hora um resumo aprovado/reprovado, quatro estatísticas (paths, operações, schemas, refs resolvidas), uma tabela de endpoints com métodos e flags de auth, e uma lista de problemas ordenada por severidade (ERRO / AVISO / INFO). Nada é enviado a um servidor — o parsing e o lint rodam inteiramente na sua máquina, então é seguro para APIs privadas e internas.

Como a ferramenta detecta referências $ref quebradas ou não resolvidas?

Ela percorre todo o documento analisado, coleta cada ponteiro "$ref" e resolve cada um. Ponteiros locais como #/components/schemas/Pet são resolvidos contra o spec usando regras de JSON-pointer (incluindo o desescape ~1 → / e ~0 → ~); se o componente alvo não existe, a ref é marcada como ERRO — esta é a causa nº1 de openapi-generator, oapi-codegen, Kiota, openapi-typescript e Redocly quebrarem ou descartarem operações silenciosamente. Refs externas ou remotas (URLs http(s)://, ou caminhos de arquivo como ./common.yaml#/Address) são marcadas como AVISO porque esta ferramenta offline não consegue baixá-las e verificá-las — resolva-as no CI com Spectral, Redocly CLI ou vacuum. A estatística 'Refs resolvidas' mostra quantas referências locais apontavam para um componente real, para você confirmar num relance que seu grafo de componentes está intacto. Culpados comuns de uma ref pendurada: um erro de digitação no nome do componente, um schema que você renomeou mas esqueceu de atualizar, ou um $ref para um caminho que vive em outro arquivo ainda não empacotado.

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.