Softonic

Validador Swagger 2.0

Etapa 1 / 2
Próximo

Cole uma definição Swagger 2.0, em JSON ou YAML, para verificar se ela tem o campo de versão swagger, um objeto info com título e versão e um objeto paths. As entradas de caminho são analisadas para ver se têm barra inicial e se contêm chaves que não são operações padrão.

Como verificar um arquivo Swagger 2.0

  1. 1

    Copie sua definição

    Copie o `swagger.json` ou `swagger.yaml` completo, começando pela linha `swagger: "2.0"`.

  2. 2

    Cole aqui

    Cole no campo do documento OpenAPI / Swagger.

  3. 3

    Execute a verificação

    Avance para a etapa de resultados para obter os erros e os avisos.

  4. 4

    Atualize e verifique de novo

    Aplique as correções no seu arquivo e cole a nova versão até o relatório ficar limpo.

O que conta como aprovado em um Swagger 2.0

Em um arquivo 2.0, a verificação de versão é atendida por uma chave swagger de nível superior. A ferramenta não confere se o valor é "2.0", então não detectará um número errado. Além da versão, ela precisa de info.title, info.version e um objeto paths.

Campos específicos do Swagger 2.0, como host, basePath, schemes, definitions e securityDefinitions, não são examinados. Um host ausente ou um bloco definitions quebrado não serão reportados.

Um exemplo prático

{
  "swagger": "2.0",
  "info": { "title": "Shop API", "version": "1.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "x-internal": true
    }
  }
}

O campo de versão, info e paths estão todos presentes, então não há erros. O relatório mostra um aviso:

Achado Tipo Motivo
Método desconhecido ‘x-internal’ em /products. Aviso A chave não é uma operação padrão nem um campo de item de caminho

O documento continua válido, porque avisos não bloqueiam a validade. Chaves de extensão de fornecedor como x-internal são legais no Swagger 2.0, então você pode mantê-la.

Migrando a partir da 2.0

Se você pretende migrar para o OpenAPI 3.x, pode colar o arquivo convertido na mesma caixa e comparar os resultados. A verificação é a mesma, com o campo openapi no lugar de swagger. Para o trabalho real de migração, use um conversor e um linter completos, porque esta ferramenta não traduz as configurações de definitions nem de host.

Quando uma verificação rápida basta

Definições Swagger 2.0 costumam ficar anos nos repositórios e são editadas à mão. Uma verificação estrutural rápida é útil quando você herda uma, quando uma ferramenta se recusa a carregá-la e você suspeita de um campo ausente, ou quando junta dois arquivos e quer ter certeza de que o resultado mantém suas seções info e paths. Para as regras completas da 2.0, incluindo definitions e configurações de segurança, use depois um linter específico.

Lembre que um relatório limpo é uma afirmação apenas sobre a estrutura. Operações sem respostas, tipos de parâmetro errados e referências não resolvidas estão fora desta verificação, então teste o arquivo também na sua ferramenta de documentação ou de geração de código.

Perguntas frequentes

Não. Ela verifica se o campo swagger ou openapi existe, não o que ele contém.

Não. Apenas o campo de versão, o objeto info, o objeto paths e as entradas de cada caminho são verificados.

Sim. O texto é lido primeiro como JSON e, se falhar, como YAML. Mantenha a indentação inalterada ao colar.

parameters, summary, description e servers no nível do caminho estão na lista de chaves aceitas, então não disparam o aviso de método desconhecido.

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