Validador OpenAPI 3.1

O que esta ferramenta faz com arquivos 3.1

A versão 3.1 alinha os schemas ao JSON Schema 2020-12. Este validador não lê o interior dos schemas. Ele inspeciona apenas o nível superior e as entradas de caminho, então recursos de schema do 3.1, como arrays de tipos ou const, não passam nem falham aqui. O valor da versão também não é verificado: qualquer campo openapi conta como presente.

Dois padrões do 3.1 para observar

O OpenAPI 3.1 permite descrever apenas webhooks e omitir paths. Esta ferramenta exige paths, então um arquivo assim é reportado com erro, mesmo que a especificação o permita. Adicionar um objeto vazio paths: {} atende à verificação.

A lista de métodos usada aqui é get, post, put, patch, delete, head, options, além de parameters, summary, description e servers. O método trace existe na especificação, mas não está nessa lista, então gera um aviso que você pode ignorar se for intencional. Avisos não tornam o documento inválido.

Um exemplo prático

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

Resultado: um erro, “objeto ‘paths’ ausente.” Adicione paths: {} e a estrutura passa.

Quando usar isto e quando ir além

Use esta página para confirmar que um arquivo 3.1 está bem formado antes de abrir um pull request ou compartilhá-lo com um parceiro. As verificações são rápidas e as mensagens são simples. Com a estrutura correta, as regras de schema do 3.1 ainda precisam de um linter completo, porque é aí que se escondem a maioria dos erros reais: declarações de tipo inválidas, referências quebradas e definições de resposta ausentes. Trate as duas etapas como complementares, não como alternativas.

Se um aviso for intencional, como trace, registre isso no seu pull request para que os revisores não se perguntem o motivo. Avisos nunca mudam o resultado de válido, então podem ser mantidos com segurança. Os erros são os itens a resolver antes de compartilhar o arquivo.