Validador OpenAPI: Verifique sua Spec API

O que é o Validador OpenAPI?

O Validador OpenAPI é uma ferramenta baseada em navegador que analisa e valida arquivos de especificação OpenAPI 3.x e Swagger 2.0. Cole uma spec em JSON ou YAML, clique em Validate e em segundos veja se a spec é estruturalmente válida, a contagem de caminhos e operações, e uma lista de avisos sobre campos ausentes importantes para geradores de SDK e ferramentas de documentação para desenvolvedores.

A ferramenta roda inteiramente no seu navegador usando a biblioteca @readme/openapi-parser carregada sob demanda. Nenhum conteúdo de spec é enviado a qualquer servidor. É gratuita sem necessidade de conta.

Use-a antes de commitar uma spec no controle de versão, antes de publicar documentação de API, ou ao depurar uma spec que uma ferramenta downstream como Swagger UI, Stoplight ou um gerador de SDK está rejeitando.

Funcionalidades principais

• Suporte a OpenAPI 3.x e Swagger 2.0: O validador aceita ambos os formatos. A biblioteca @readme/openapi-parser subjacente lida com ambas as versões de especificação, incluindo OpenAPI 3.1.
• Entrada JSON e YAML: A ferramenta tenta JSON.parse primeiro, depois recorre ao js-yaml para entrada YAML.
• Validação estrutural com mensagens de erro precisas: Quando a validação falha, as mensagens de erro do parser são divididas por quebras de linha e exibidas individualmente.
• Avisos de linting: Mesmo quando uma spec é estruturalmente válida, a ferramenta verifica três problemas comuns de qualidade: info.description ausente, operações sem description nem summary, e operações sem operationId.
• Contagens de endpoints e operações: Após validação bem-sucedida, tiles de resumo mostram o título da API, string de versão, contagem total de caminhos e contagem total de operações.
• Botão Carregar Exemplo: Insere uma spec OpenAPI 3.0 mínima mas completa com um único endpoint GET /users.
• Histórico de validação: Specs anteriores são salvas no IndexedDB do navegador (recurso de supporter).
• Processamento 100% no cliente: Parser e validador rodam no navegador. O conteúdo da spec nunca sai da sua máquina.

Como usar o Validador OpenAPI

Passo 1: Colar sua Spec

Clique na grande área de texto rotulada "OpenAPI Specification (JSON or YAML)" e cole o conteúdo da sua spec. Para YAML, inclua a declaração de versão no topo (openapi: "3.0.0" ou swagger: "2.0").

Para ver a ferramenta em ação primeiro, clique no botão "Load Example" no canto superior direito da área de texto.

Passo 2: Clicar em Validate Spec

Clique no botão "Validate Spec" abaixo da área de texto. O botão mostra "Validating..." enquanto o parser está rodando.

Passo 3: Revisar o resultado da validação

O painel de resultado aparece com um de dois títulos:

• "✓ Valid OpenAPI Specification" em verde — a spec passou na validação estrutural.
• "✗ Validation Failed" em vermelho — a spec tem erros estruturais que devem ser corrigidos.

Passo 4: Ler os tiles de resumo (Specs válidas)

Para specs que passam na validação, quatro tiles de resumo aparecem:

• Title — o valor de info.title
• Version — o valor de info.version
• Paths — número total de entradas de caminhos
• Operations — número total de combinações método HTTP+caminho

Passo 5: Tratar avisos

Três tipos de avisos são exibidos mesmo em specs válidas:

1. info.description ausente — a spec não tem uma descrição geral da API.
2. Operações sem description ou summary — reportado como contagem.
3. Operações sem operationId — geradores de SDK usam operationId para nomear métodos gerados.

Exemplos práticos

Exemplo 1: Encontrar um campo obrigatório ausente

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

Exemplo 2: Spec válida com avisos de qualidade

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

Exemplo 3: Verificar uma spec grande rapidamente

Após colar uma spec de API interna com 500 caminhos, os tiles de resumo mostram "Paths: 147" e "Operations: 312".

Dicas e boas práticas

Valide após cada mudança estrutural. Adicionar um novo caminho, alterar uma $ref ou modificar um schema pode introduzir erros. A validação leva menos de dois segundos.

Trate avisos de operationId como bloqueadores para workflows de SDK. Deixá-los sem definir significa que os nomes de métodos gerados serão derivados de caminhos.

Use o exemplo como modelo inicial. O exemplo embutido é uma spec OpenAPI 3.0 completa, válida e mínima.

Separe validade estrutural de correção semântica. O validador confirma que sua spec segue o schema OpenAPI, não que descreve com precisão sua API real.

Corrija erros do topo para baixo. Uma única definição de schema ausente pode causar erros $ref em cascata em toda a spec.

Problemas comuns e solução de problemas

"Parse error: ..." — a entrada não é JSON válido nem YAML válido. Causas comuns: vírgula final no JSON, indentação YAML inconsistente ou caractere de tabulação na indentação YAML.

Validação falha em uma spec que o Swagger UI aceita. O Swagger UI é tolerante com erros. Este validador aplica validação estrita de schema.

Avisos aparecem mesmo após adicionar descrições. Confirme que adicionou description dentro de info, não apenas em caminhos individuais.

A ferramenta parece lenta no primeiro uso. As bibliotecas são carregadas dinamicamente no primeiro clique de validação.

Privacidade e segurança

O Validador OpenAPI processa sua spec inteiramente no navegador. A biblioteca @readme/openapi-parser roda localmente — nenhum conteúdo de spec é enviado a qualquer serviço externo ou servidor. A ferramenta funciona completamente offline após o carregamento da página e da biblioteca do parser.

Perguntas frequentes

O Validador OpenAPI é gratuito? Sim. Sem custo, conta ou limite de uso.

Quais versões do OpenAPI são suportadas? Swagger 2.0, OpenAPI 3.0.x e OpenAPI 3.1.x.

Posso colar YAML ou precisa ser JSON? Ambos os formatos funcionam.

A ferramenta valida meus endpoints de API reais? Não. O validador verifica apenas se o arquivo de spec é estruturalmente correto.

Por que minha spec falha aqui mas funciona no Swagger UI? O Swagger UI renderiza specs com tolerância a erros. Este validador aplica validação estrita de schema.

O que significa "operationId required for SDK generation"? Geradores de SDK nomeiam métodos gerados com base nos valores de operationId. Sem eles, os nomes são construídos a partir do método HTTP e caminho.

Há falsos positivos nos avisos? As três verificações de aviso são conservadoras. A verificação de info.description só é acionada quando o campo está ausente ou vazio.

Posso validar um arquivo de spec em vez de colá-lo? A ferramenta aceita apenas texto colado — não há botão de upload de arquivo.

O painel de histórico salva o conteúdo da minha spec? Sim. Salvo localmente no IndexedDB do navegador.

O que acontece se eu colar uma spec vazia? O botão Validate fica desabilitado quando a área de texto está vazia.

Ferramentas relacionadas

• Em breve: Gerador de Mock de API — gere dados de resposta mock a partir da sua spec validada para uso no desenvolvimento frontend.
• Em breve: Suite de Design de API — projete e itere sobre a estrutura da API antes de exportar para o formato OpenAPI.
• Formatador JSON — formate e valide a estrutura JSON da sua spec antes de colá-la no validador.

Experimente o Validador OpenAPI agora: Validador OpenAPI