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

Gerador de Cartão CSS

Crie o CSS de um contêiner de cartão: fundo, borda, raio dos cantos, espaçamento interno e sombra suave, com pré-visualização imediata e código para copiar e colar.

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.

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.

Visualizador de Markdown

Escreva Markdown e veja a renderização HTML atualizar ao vivo. Sintaxe com estilo GitHub, incluindo tabelas, listas de tarefas, blocos de código cercados e autolinks.

Gerador de Docker Compose

Gere um docker-compose.yml a partir de definições de serviços com imagem, portas e volumes, com padrões de boas práticas.

Conversor de base numérica

Converta números entre binário, octal, decimal, hexadecimal e qualquer base personalizada de 2 a 36, com o detalhamento posicional.

Ferramenta disponível em outros idiomas