Ir para o conteúdo principal
Bethemesh
Desenvolvimento

Validador OpenAPI e Swagger

Verifique uma descrição de API em JSON ou YAML sem a enviar para um servidor.

Cole ou importe um documento JSON/YAML autónomo e inicie a validação. O relatório apresenta os erros e explica o âmbito das verificações.

Esta ferramenta foi útil?

Como funciona esta ferramenta?

Uma descrição OpenAPI funciona como contrato entre quem desenvolve, documenta e utiliza uma API. Uma indentação YAML incorreta, um campo obrigatório em falta ou uma referência impossível de resolver podem impedir a sua utilização. Este validador ajuda a localizar esses erros em JSON ou YAML diretamente no navegador. Suporta Swagger 2.0, OpenAPI 3.0.0–3.0.4 e OpenAPI 3.1.0–3.1.2, com o âmbito indicado no relatório.

A verificação começa pela sintaxe: o texto tem de ser interpretável como um único documento JSON ou YAML, sem chaves duplicadas. Seguem-se a versão e a estrutura esperada, incluindo as informações da API e as operações descritas. Um ficheiro sintaticamente correto pode, portanto, não cumprir o esquema OpenAPI da sua versão.

As referências internas usam JSON Pointer, por exemplo #/components/responses/Ok, para indicar posições no mesmo documento. O validador verifica a sua resolução e distingue referências reais de chaves $ref nos dados de um exemplo. As referências a outros ficheiros ou esquemas remotos são recusadas; nenhum mecanismo de resolução os descarrega.

As verificações adicionais abrangem os operationId de rotas e webhooks, os parâmetros de caminho e os tipos de palavras-chave dos esquemas 3.1. Um resultado positivo continua a ser parcial: não verifica todas as restrições semânticas, formatos ou a validade dos exemplos. Dialetos personalizados, $id, âncoras e referências dinâmicas são assinalados como não suportados.

Um caminho de diagnóstico como /paths/~1health/get/responses indica o campo responses de GET /health: em JSON Pointer, ~1 representa uma barra oblíqua. É apresentada uma linha quando a posição pode ser localizada no texto de origem. Comece pela primeira causa clara antes de tratar os diagnósticos secundários do mesmo objeto incompleto.

Como usar esta ferramenta

  1. Fornecer o documento

    Cole a descrição ou importe um ficheiro JSON, YAML ou YML. Reúna previamente as referências distribuídas por vários ficheiros.

  2. Iniciar as verificações

    Clique em Validar. O processamento decorre no navegador e termina ao fim de dez segundos, no máximo.

  3. Corrigir os caminhos indicados

    Comece pelos erros de sintaxe, corrija os campos assinalados e volte a validar.

Casos de uso

Rever um contrato API

Verifique um ficheiro antes do commit ou de o entregar a outro programador.

Diagnosticar uma exportação

Localize erros de estrutura numa descrição produzida por um framework ou gerador.

Examinar uma API privada

Analise uma descrição interna sem enviar o conteúdo nem chamar os endpoints.

Exemplos

Um documento autónomo com uma referência interna

Cole este documento completo para descrever GET /health. A resposta 200 reutiliza o componente Ok do mesmo ficheiro. Verifique-se um contrato documental; não é enviado nenhum pedido GET a um servidor.

Entrada

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      responses:
        "200":
          $ref: "#/components/responses/Ok"
components:
  responses:
    Ok:
      description: OK

Resultado

Válida no âmbito verificado
Operações HTTP declaradas: 1

Um campo obrigatório em falta

Este YAML pode ser interpretado, mas falta info.version. Acrescente, por exemplo, version: 1.0.0 dentro de info. Um objeto paths vazio não é, por si só, a causa do erro. A linha indicada depende da posição do campo no ficheiro.

Entrada

openapi: 3.1.0
info:
  title: Health API
paths: {}

Resultado

Descrição a corrigir
Caminho: /info
Estrutura não conforme com a especificação.
Detalhe: required: version

Uma referência interna impossível de resolver

O documento continua a conter o componente Ok, mas a resposta pede Absent. Corrija o nome na referência. Se o substituir por um URL externo, o diagnóstico passa a ser uma referência externa recusada e o ficheiro remoto não é carregado.

Entrada

openapi: 3.1.0
info:
  title: Health API
  version: 1.0.0
paths:
  /health:
    get:
      responses:
        "200":
          $ref: "#/components/responses/Absent"
components:
  responses:
    Ok:
      description: OK

Resultado

Descrição a corrigir
Caminho: /paths/~1health/get/responses/200/$ref
Referência interna não encontrada.

Dicas e boas práticas

  • info.version é a versão da sua API; openapi indica a versão do formato de descrição. Não são intercambiáveis.
  • Um caminho /users/{id} tem de declarar o parâmetro id no caminho ou na operação. Um parâmetro de consulta chamado id não substitui um parâmetro de caminho.
  • Para vários ficheiros, produza primeiro um documento autónomo com a ferramenta de agrupamento habitual. O limite é um milhão de caracteres; os aliases YAML e a complexidade também são limitados, com um tempo máximo de dez segundos.

Fontes e referências

Perguntas frequentes

Uma validação bem-sucedida garante que a API funciona?

Não. O validador verifica parte da descrição, não as respostas do servidor, os direitos de acesso ou as regras de negócio. Nenhum endpoint é chamado. O relatório explica os limites das verificações.

Como verifico uma descrição com vários ficheiros?

Reúna-a localmente num documento autónomo com as suas ferramentas habituais. Não são obtidos ficheiros ligados.

O OpenAPI 3.2 é suportado?

Ainda não nesta versão. Uma versão não suportada é assinalada sem ser confundida com um erro de sintaxe.

Que verificações são efetuadas?

O documento é comparado com o esquema estrutural da sua versão. Também se verificam as referências JSON Pointer internas, os tipos de palavras-chave dos esquemas 3.1, os operationId de rotas e webhooks e os parâmetros de caminho. Nem todos os formatos, exemplos, dados reais e restantes restrições semânticas são verificados.

Ferramentas relacionadas

Continue com estas ferramentas

Ferramentas semelhantes ou complementares a esta.

Ferramentas semelhantes

Validador de esquema JSON

Valide um documento JSON com um esquema e localize precisamente cada erro.

DesenvolvimentoEm destaqueUtilizar esta ferramenta

Gerador de pedidos API

Crie um pedido HTTP completo com método, URL, parâmetros, cabeçalhos e corpo.

DesenvolvimentoUtilizar esta ferramenta