Softonic

Validador de spec OpenAPI online

Etapa 1 / 2
Próximo

Cole sua spec OpenAPI ou Swagger acima para obter uma lista de erros e avisos. Esta página explica o que cada mensagem significa e como corrigi-la, para sair de um relatório vermelho para um limpo rapidamente. Erros tornam o documento inválido; avisos não.

Como verificar uma spec e agir sobre o relatório

  1. 1

    Cole a spec

    Cole seu documento em JSON ou YAML no campo.

  2. 2

    Abra os resultados

    Avance para a etapa de resultados para ver uma mensagem de válido ou uma lista de erros.

  3. 3

    Relacione cada mensagem

    Encontre a mensagem na tabela abaixo e aplique a correção no seu arquivo de origem.

  4. 4

    Cole de novo

    Execute novamente até não restar nenhum erro e então decida quais avisos valem a correção.

Como ler as mensagens de erro

Mensagem Significado Correção
Não foi possível interpretar como JSON ou YAML. O texto não é legível em nenhum dos dois formatos Corrija a sintaxe: vírgulas sobrando, indentação errada, chaves sem fechamento
Campo de versão ‘openapi’ ou ‘swagger’ ausente. Não há chave de versão no nível superior Adicione openapi: 3.0.3 ou swagger: "2.0"
Objeto ‘info’ ausente. Não há seção info Adicione info com título e versão
info.title é obrigatório. info não tem título Adicione um title em info
info.version é obrigatório. info não tem versão Adicione um version em info (a versão da sua API)
Objeto ‘paths’ ausente. Não há seção paths Adicione paths, mesmo que vazio no começo

Os erros são o que decide se o documento é reportado como válido. Corrija todos antes de qualquer outra coisa.

Como ler os avisos

Mensagem Significado Correção
O caminho ‘x’ deve começar com ‘/’. Uma chave em paths não tem barra inicial Renomeie para /x
Método desconhecido ‘x’ em /caminho. Uma chave em um caminho não está na lista conhecida Procure um erro de digitação, ou ignore se for uma extensão deliberada ou trace

A lista conhecida é get, post, put, patch, delete, head, options, parameters, summary, description e servers. Extensões de fornecedor que começam com x- não estão nela, então também aparecem como avisos.

O que uma verificação online não consegue dizer

O relatório cobre apenas a estrutura. Ele não segue links $ref, não verifica definições de schema e não sinaliza operationId ausentes. Considere que uma aprovação confirma que o arquivo tem o formato de um documento OpenAPI, e use um linter completo antes de publicar documentação ou gerar código cliente.

Dicas para revisar um relatório longo

Comece pelo topo: um erro de análise significa que nada mais é confiável, então corrija-o antes de tudo. Em seguida trate os campos de nível superior ausentes, porque são rápidos de adicionar. Só depois veja os avisos de caminhos. Depois de cada rodada de edições, cole o documento inteiro e não um trecho, já que as verificações precisam do documento completo para encontrar info e paths. Um relatório sem erros e com alguns avisos deliberados é um fim normal e aceitável.

Perguntas frequentes

Erros significam que o documento é reportado como não válido. Avisos apontam itens que merecem atenção, como um caminho sem barra inicial, mas não mudam o resultado de válido.

Não necessariamente. Significa que a estrutura de nível superior está no lugar. Schemas, referências e respostas não são examinados.

As chaves em um caminho são comparadas com uma lista fixa de métodos HTTP e de alguns campos de item de caminho. Uma chave x- não está nela, então é marcada como aviso. Você pode mantê-la.

Não. Eles seguem a ordem das verificações: primeiro o campo de versão, depois info e por último paths. Não há números de linha.

Ferramentas relacionadas

Contador de FPS

Meça o FPS do navegador com requestAnimationFrame: suavização, taxa de quadros mínima e máxima, limite de alerta e gráfico opcional. Roda localmente, sem upload nem API.

Gerador de Configuração Webpack

Crie um webpack.config.js para webpack 5 com JavaScript puro, React ou Vue: TypeScript, Babel, CSS ou Sass, imagens, HtmlWebpackPlugin, servidor de desenvolvimento e a linha de npm install.

Conversor de Tamanho de Arquivo

Converta entre bytes, KB, MB, GB, TB e as unidades binárias IEC (KiB, MiB, GiB, TiB), combinando decimal e binário como preferir.

Gerador de textura de ruído

Gere uma textura de ruído em SVG que se repete sem emendas, com opacidade, frequência do grão, tipo de ruído e cor de fundo ajustáveis, e copie o CSS já pronto.

Gerador de Licença

Gere o texto completo de licenças de código aberto com seu nome e ano preenchidos. Abrange licenças MIT, Apache 2.0, GPLv3, BSD-3, MPL-2.0 e CC.

Desofuscador de JavaScript

Desofusque JavaScript minificado ou empacotado com renomeação de variáveis, decodificação de arrays de strings, reversão de achatamento de fluxo de controle e embelezamento.

Ferramenta disponível em outros idiomas

Guias e casos de uso