Este visualizador e validador de OpenAPI lê um documento OpenAPI 3.0, 3.1 ou Swagger 2.0 em YAML ou JSON e o mostra como documentação de API navegável: cada endpoint agrupado por tag, com seus parâmetros, corpo da requisição, respostas e schemas, além de um comando cURL pronto para rodar. Cole a especificação ou abra o arquivo; nada é enviado, então APIs internas e ainda não lançadas continuam privadas.
O validador executa 23 verificações estruturais tiradas das especificações, todas listadas na página: info e paths presentes, respostas com descrição e códigos de status válidos, todo {parameter} de um path declarado como parâmetro de path obrigatório, operationIds únicos, $refs que se resolvem e requisitos de segurança que citam um esquema definido. São os erros que quebram geradores de código e ferramentas de documentação. Não é uma validação completa contra o JSON Schema oficial da especificação, então uma especificação aprovada aqui ainda pode ter, por exemplo, uma palavra-chave de schema escrita errado. $refs externos para outros arquivos são listados, mas não baixados.
Como usar
- Cole o seu openapi.yaml, openapi.json ou swagger.json, ou abra o arquivo. Uma API de exemplo é carregada para começar.
- Leia a linha de status e a lista de Validação. Cada problema cita a regra e onde ele está (por exemplo, paths./pets/{id}.get).
- Navegue pela documentação: as operações são agrupadas por tag; clique em uma para ver parâmetros, corpo da requisição, respostas e schemas.
- Filtre por path, resumo ou operationId para encontrar um endpoint em uma especificação grande.
- Copie o exemplo de cURL de uma operação e substitua o placeholder <TOKEN> ou <API_KEY> pelas suas credenciais.
Perguntas frequentes
Como visualizar um arquivo Swagger ou OpenAPI?
Cole o YAML ou JSON na caixa ou abra o arquivo. O visualizador detecta a versão (swagger: "2.0" ou openapi: 3.0.x / 3.1.x), lista os endpoints agrupados por tag e permite expandir cada um para ver os parâmetros, o corpo da requisição, as respostas e os schemas resolvidos. Depois que a página carrega, ele funciona offline.
O que o validador de OpenAPI verifica?
Regras estruturais da especificação: um campo de versão suportado; info com title e version; paths começando com /; operações com responses não vazio, com descrições e códigos de status válidos; parâmetros do template de path declarados e obrigatórios; parâmetros com name, um in válido e um schema; nenhum parâmetro ou operationId duplicado; corpos de requisição com content; $refs que se resolvem; e requisitos de segurança que citam esquemas definidos. A lista completa está na página, em “O que é verificado”. Ele não valida cada palavra-chave de schema contra o JSON Schema oficial.
Por que o meu parâmetro de path não declarado é um erro?
A especificação exige que todo {name} em um template de path tenha um parâmetro correspondente com in: path e required: true, no nível do path ou da operação. Alguns validadores que só conferem o documento contra o JSON Schema aceitam a falta dele, mas aí os geradores de código produzem uma função sem argumento para ele, e as ferramentas de documentação mostram um endpoint que você não consegue chamar corretamente.
Ele lê OpenAPI 3.1 e Swagger 2.0?
Sim. Os parâmetros body e formData do Swagger 2.0 aparecem como corpo da requisição, com produces e consumes como media types, então as três versões são lidas da mesma forma. As diferenças do OpenAPI 3.1 são respeitadas: paths é opcional quando há components ou webhooks, responses é opcional (aqui, um aviso) e type: [string, "null"] aparece como nullable.
Ele carrega arquivos $ref externos?
Não. Um $ref para outro arquivo ou URL (por exemplo ./schemas/user.yaml) é listado como aviso e mostrado como não resolvido, porque a página não consegue ler arquivos que você não abriu e não baixa URLs por conta própria. Junte antes uma especificação de vários arquivos em um único documento, por exemplo com redocly bundle ou swagger-cli bundle.
A minha especificação de API é enviada?
Não. A análise, a validação e a renderização acontecem no seu navegador. A especificação nunca é enviada a lugar nenhum.
OpenAPI 3.x e Swagger 2.0: o que mudou
• Campo de versão: swagger: "2.0" virou openapi: 3.0.x e depois 3.1.x.
• Servidores: o 2.0 tem host, basePath e schemes; o 3.x tem uma lista servers com variáveis.
• Corpos de requisição: o 2.0 usa um parâmetro com in: body (ou formData); o 3.x tem requestBody com content por media type.
• Partes reutilizáveis: no 2.0, definitions, parameters e responses ficam no nível superior; o 3.x as coloca em components, junto com securitySchemes, requestBodies e examples.
• O 3.1 alinha os schemas com o JSON Schema 2020-12: type pode ser uma lista (["string", "null"] em vez de nullable: true), examples é um array, e foram adicionados os webhooks.
Os erros que mais quebram ferramentas de API
• Parâmetros de path não declarados, ou declarados sem required: true.
• Um $ref com erro de digitação (#/components/schema/User em vez de schemas), que deixa parte da documentação vazia.
• operationIds duplicados, que fazem os geradores de código falhar ou sobrescrever métodos.
• Respostas sem description (ela é obrigatória, mesmo que seja só "OK").
• Um requisito de segurança que cita um esquema não definido, de modo que o cliente gerado não tem como se autenticar.
