Como usar: Validador OpenAPI / Swagger
- Cole seu
openapi.yaml/swagger.jsonou abra o arquivo. - A versão (OpenAPI 3.1, 3.0 ou Swagger 2.0) é detectada automaticamente.
- Corrija primeiro os erros de schema — cada um mostra sua localização no documento.
- Revise as verificações adicionais e a lista de endpoints.
O que é verificado
| Verificação | Detalhes |
|---|---|
| Schema oficial | O documento é validado contra o JSON Schema da OpenAPI Initiative para a versão dele (3.1, 3.0 ou Swagger 2.0): campos obrigatórios, chaves permitidas, tipos de valor |
$ref quebrada | Toda referência local (#/components/schemas/Pet) precisa apontar para algo que existe |
operationId único | Duplicados quebram geradores de SDK e links da documentação |
| Parâmetros de path | Cada {param} em um path precisa ser declarado com in: path e required: true, e vice-versa |
| Respostas | Cada operação precisa de pelo menos uma resposta |
| Dicas | operationId, servers ou info.description ausentes |
Versões do OpenAPI
- Swagger 2.0 —
swagger: "2.0",definitions,host/basePath. - OpenAPI 3.0 —
components,servers,requestBody; os schemas são um subconjunto do JSON Schema draft-04 comnullable. - OpenAPI 3.1 — totalmente alinhado ao JSON Schema 2020-12 (
type: [string, "null"]no lugar denullable), adicionawebhooks.
Limites
Referências externas a outros arquivos ou URLs não são buscadas — faça o bundle de specs com vários arquivos antes (por exemplo, com redocly bundle). A validação de schema aponta problemas estruturais; regras de estilo, como convenções de nomenclatura, exigem um linter como o Spectral. Valide payloads de exemplo contra seus schemas com o validador JSON Schema, verifique a sintaxe YAML com o validador YAML e teste a API em produção com o testador de API.
Também pesquisado como: validador swagger, validador openapi, validar openapi, validador openapi 3.1, validador swagger 2.0, lint openapi, validador de spec de api.
Ferramentas que combinam com: Validador OpenAPI / Swagger
- Formatação JSON — Cole o JSON aqui para formatá-lo, compactá-lo ou validá-lo.
- Conversor cURL — Cole um comando curl, da documentação de uma API ou da opção “Copiar como cURL” do DevTools do seu navegador, e receba código pronto para usar em seis linguagens, com headers, corpo e autenticação preservados.
- Testador de JSONPath — Digite uma consulta JSONPath e veja na hora o que ela seleciona, com o caminho exato de cada resultado.
- JSON para YAML — Cole seu JSON e receba YAML limpo para manifests do Kubernetes, Docker Compose, GitHub Actions ou qualquer arquivo de configuração.
Perguntas frequentes
Ele suporta OpenAPI 3.1?
Sim — OpenAPI 3.1.x, 3.0.x e Swagger 2.0 são validados cada um contra o schema oficial correspondente.
Por que aparecem tantos erros para um único problema?
Os schemas oficiais usam alternativas (oneOf), então um único valor errado pode falhar em vários ramos. A ferramenta filtra essas mensagens e mostra as mais específicas; corrija a primeira e valide novamente.
Ele consegue seguir $refs para outros arquivos?
Não, apenas referências dentro do mesmo documento. Faça o bundle de specs com vários arquivos em um único arquivo antes.
A minha spec de API é enviada para algum servidor?
Não. A validação roda inteiramente no seu navegador, então os designs internos das suas APIs continuam privados.
Posso instalar o Validador OpenAPI / Swagger como um aplicativo da web e usá-lo offline?
Sim. O Validador OpenAPI / Swagger é um aplicativo da web instalável (PWA) — instalado a partir do seu navegador, não baixado de uma loja de aplicativos. Clique em “Instalar aplicativo” na parte superior desta página no Chrome ou no Edge (Windows, macOS, Linux, ChromeOS) ou, no Android, use “Compartilhar” → “Adicionar à tela inicial” no iPhone e no iPad, ou “Arquivo” → “Adicionar ao Dock” no Safari 17+ em um Mac. Em seguida, ela se abre em uma janela própria com seu próprio ícone e, como é executada inteiramente no seu navegador, continua funcionando offline. O Firefox no desktop não permite a instalação de aplicativos da web. Como funciona a instalação.