Softonic

Validador OpenAPI

Etapa 1 / 2
Próximo

Cole um documento OpenAPI ou Swagger, em JSON ou YAML, e este validador verifica sua estrutura básica. Ele confirma que o documento é analisado, que tem um campo de versão openapi ou swagger, um objeto info com título e versão e um objeto paths, e então sinaliza os caminhos que não começam com barra e os métodos HTTP desconhecidos. É uma verificação de estrutura rápida, não um validador de JSON Schema completo.

Como a validação é executada

  1. 1

    Cole o documento

    JSON ou YAML, para OpenAPI 2 (Swagger) ou OpenAPI 3.

  2. 2

    Analise-o

    O validador analisa o documento como JSON e recorre à análise YAML se isso falhar.

  3. 3

    Verifique os campos obrigatórios

    Ele confirma um campo de versão `openapi` ou `swagger`, um objeto `info` com `title` e `version` e um objeto `paths`.

  4. 4

    Examine os caminhos

    Cada caminho é verificado quanto a uma barra inicial, e cada chave de operação é comparada com os métodos HTTP conhecidos.

  5. 5

    Leia o relatório

    Erros bloqueiam a validade; avisos apontam os caminhos sem barra inicial e os métodos desconhecidos.

O que este validador verifica

Verificação Resultado se falhar
O documento é analisado como JSON ou YAML Erro
Existe o campo openapi ou swagger Erro
Existe o objeto info Erro
Existe info.title Erro
Existe info.version Erro
Existe o objeto paths Erro
Cada caminho começa com / Aviso
As chaves de operação são métodos HTTP conhecidos Aviso

Um documento que passa por todos os erros é reportado como estruturalmente válido. Os avisos não bloqueiam a validade; destacam pontos que vale a pena corrigir.

O que ele não verifica

Isto é uma verificação de estrutura, não um validador de especificação completo. Ele não:

  • valida cada nó contra o JSON Schema oficial da sua versão;
  • resolve as referências $ref nem confirma que os componentes para os quais elas apontam existem;
  • verifica se os parâmetros de caminho são declarados e usados de forma consistente;
  • verifica se os valores de operationId existem ou são únicos;
  • reporta os números de linha dos erros.

Para essa profundidade, execute um validador de CLI dedicado como redocly lint, swagger-cli validate ou spectral lint. Use esta ferramenta para uma verificação rápida antes de fazer commit ou compartilhar uma especificação.

Versões do OpenAPI na prática

Versão Notas
Swagger 2.0 Ainda amplamente implantada; usa swagger: "2.0"
OpenAPI 3.0.x A linha 3.x mais comum
OpenAPI 3.1.0 Alinhada com JSON Schema 2020-12

Este validador aceita o campo openapi (3.x) ou o campo swagger (2.0), então todas passam na verificação de versão.

Um documento mínimo que passa

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Todos os campos obrigatórios estão presentes, o único caminho começa com barra, e get é um método conhecido, então é reportado como estruturalmente válido.

Perguntas frequentes

Swagger foi o nome original da especificação, doada à Linux Foundation em 2015 e renomeada para “OpenAPI” a partir da versão 3.0. “Swagger” agora se refere às ferramentas (Swagger UI, Swagger Editor). A especificação em si é OpenAPI. Este validador aceita tanto o campo de versão swagger (2.0) quanto openapi (3.x).

Não. Ele verifica a estrutura básica: que o documento é analisado, tem um campo de versão, um objeto info com título e versão e um objeto paths, e avisa sobre caminhos sem barra inicial e métodos desconhecidos. Ele não valida cada nó contra o JSON Schema oficial. Para isso, use redocly lint ou spectral lint.

Não. Ele não segue as referências $ref nem verifica se os componentes para os quais elas apontam existem. Para referências entre arquivos, agrupe primeiro o documento com uma ferramenta como redocly bundle ou swagger-cli bundle, e depois execute um validador completo.

Não. Ele apenas inspeciona o documento que você cola, não o seu código em execução. Ele não pode saber se a sua API realmente retorna o que a especificação descreve. Ferramentas de teste de contrato como Dredd ou Schemathesis fazem isso.

Ferramentas relacionadas

Referência da Tabela ASCII

Tabela ASCII completa de 0 a 127 com valores decimais, hexadecimais, octais e binários e notação de referência numérica HTML, incluindo NUL, LF e DEL.

Referência de Caracteres HTML

Lista pesquisável de entidades HTML, seus códigos nomeados e numéricos, e uma cópia com um clique para caracteres e símbolos especiais.

Referência de atalhos de teclado

Pesquise atalhos padrão documentados do VS Code, Chrome e Bash com GNU Readline no macOS, Windows e Linux.

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 EditorConfig

Gere um arquivo .editorconfig com suas regras de estilo e tamanho de indentação, fim de linha, charset e espaços em branco para formatação consistente entre IDEs e editores.

Validador de Email

Valide um endereço de email: verificação de sintaxe RFC 5322, consulta de registro MX em tempo real, além de detalhes de parte local, domínio e comprimento. Nenhum email é enviado.

Ferramenta disponível em outros idiomas