Validação do Especificação OpenAPI Capturar Erros no Seu Arquivo Swagger Antes que os Clientes Quebrem

Um esquema OpenAPI é um contrato entre sua API e tudo o que a consome — clientes gerados automaticamente, servidores simulados, documentação e frameworks de teste. O problema é que, diferentemente do código de aplicação, um esquema quebrado não gera uma exceção. Ele produz silenciosamente saídas incorretas no downstream, e a primeira vez que você ouve sobre isso é quando um SDK de cliente gera código inútil ou sua documentação renderiza com endpoints ausentes.

Capturar erros no esquema cedo — antes que eles atinjam os consumidores — é a função da validação do esquema. Este artigo aborda o que validar, onde os erros comuns escondem-se e como executar a validação localmente e no navegador.

Por que a sua forma de esquema importa além da documentação

A maioria dos desenvolvedores pensa em um esquema OpenAPI como um artefato de documentação — algo que alimenta a Swagger UI ou o Redoc. Isso é apenas metade da imagem. O esquema também é a fonte de verdade para:

• Geração de código — Ferramentas como openapi-generator e swagger-codegen produzem stubs de servidor e bibliotecas de cliente diretamente a partir do esquema. Um esquema mal-formulado produz código mal-formulado.
• Testes de contrato — Frameworks como Dredd e Schemathesis testam sua API ativa contra seu esquema. Um esquema inválido significa que os testes não conseguem rodar ou geram resultados falsos.
• Servidores simulados — Ferramentas como Prism e semelhantes servem respostas simuladas com base nos valores de exemplo e esquemas do seu esquema. Esquemas errados produzem mocks errados.
• Configuração de gateway — Serviços como AWS API Gateway, Kong e outros podem importar esquemas OpenAPI para configurar roteamento, autenticação e validação. Um esquema inválido silenciosamente descarta ou configura incorretamente rotas.

Nenhum desses ferramentas vai dizer a você de forma legível que o esquema está errado. Eles vão simplesmente crashar, produzir lixo ou ignorar silenciosamente a parte afetada. Validar seu esquema antes que ele chegue a esses consumidores é inegociável.

OpenAPI 2.0 vs 3.0 vs 3.1: As diferenças de versão que atrapalham as pessoas

A versão que você declara no topo do seu esquema altera as regras aplicáveis — e muitos erros surgem de misturar convenções entre versões.

• OpenAPI 2.0 (Swagger) — Usa swagger: "2.0". Corpos de requisição vão para parameters com in: body. Definições vivem em definitions, e não components/schemas. Sem suporte para oneOf, anyOf, ou not no nível de esquema.
• OpenAPI 3.0.x — Usa openapi: "3.0.x". Corpos de requisição passam para requestBody. Esquemas consolidam sob components. Suporta oneOf, anyOf, allOfe, e not. Adiciona links e callbacks.
• OpenAPI 3.1.0 — Alinha totalmente com o JSON Schema draft 2020-12. nullable é substituída por type: [string, null]. exclusiveMinimum/exclusiveMaximum mudança de booleans para números. $schema agora é permitida nos esquemas.

O erro mais comum de migração: copiar um esquema 2.0 e alterar o campo de versão para 3.0.0 sem mover os corpos de requisição de parameters para requestBody. O esquema parece válido em JSON/YAML, mas falha na validação semântica.

Erros comuns no esquema e onde eles se escondem

Erros no esquema seguem padrões previsíveis. Aqui estão os que aparecem mais frequentemente em bancos de código reais:

Campos obrigatórios ausentes

Cada operação deve ter pelo menos uma resposta 2xx definida. Cada parâmetro precisa ter um name e um in valor. Parâmetros de caminho declarados na URL (por exemplo, /users/{id}) devem ter um objeto de parâmetro correspondente com in: path e required: true. Ausência de qualquer um desses produz um esquema tecnicamente parseável que quebra validadores e geradores de código downstream.

Caminhos $ref inválidos

A $ref que apontam para um componente inexistente é uma das principais falhas no esquema. O referência parece válida — $ref: "#/components/schemas/UserProfile" — mas o esquema-alvo foi renomeado ou excluído. Os analisadores JSON/YAML aceitam isso sem reclamar. Apenas um validador do esquema percebe isso.

Caminhos externos $ref são ainda mais arriscados — eles apontam para arquivos ou URLs em outros locais que podem não ser acessíveis em todos os ambientes. Inline essas referências antes de distribuir seu esquema ou usá-lo com ferramentas que não resolvem externos.

Tipos de esquema incorretos

Desalinhamentos nos tipos de esquema são sutis. Declaração de type: integer em um campo que retorna valores de tipo float. Uso de format: date-time com um campo que retorna timestamps Unix (inteiros). Definição de um enum com valores que não correspondem ao declarado type. Esses passam a análise YAML, mas produzem propriedades mal tipadas nos clientes gerados.

Referências circulares

Um esquema que referencia a si mesmo — diretamente ou através de uma cadeia de $ref valores — causa geradores de código e ferramentas de documentação a entrar em loop infinito ou crashar. A maioria dos validadores detecta e relata referências circulares, mas podem ser difíceis de desentrelhar em esquemas profundamente aninhados. A solução é geralmente quebrar o ciclo com um esquema dedicado para o caso recursivo.

Erros estruturais versus erros semânticos

Erros de validação não são todos os mesmos. Entender a diferença ajuda você a priorizar as correções:

• Erros estruturais — O esquema não se conforma com o esquema OpenAPI. Campos obrigatórios estão ausentes, nomes de propriedades estão errados ou os tipos não correspondem ao formato do esquema. Esses são capturados por validação estrita de esquema e bloqueiam a maioria das ferramentas.
• Erros semânticos — O esquema é estruturalmente válido em JSON/YAML e passa a validação de esquema, mas descreve algo que não pode funcionar. Um endpoint com um parâmetro de caminho na URL mas sem definição de parâmetro. Um esquema de resposta que usa allOf com campos obrigatórios conflitantes. Esses são capturados por regras de lint mais profundas, e não por verificações básicas de esquema.

A maioria dos validadores online e das ferramentas de linha de comando captura erros estruturais. Capturar erros semânticos exige um linter baseado em regras, como o Spectral, que avalia a lógica e a consistência interna do esquema.

components/schemas: Definições DRY versus esquemas inline

O OpenAPI 3.0 introduziu components/schemas como o local canônico para definir esquemas reutilizáveis. O trade-off:

• Esquemas compartilhados em components — Corretos quando o mesmo esquema aparece em vários lugares (por exemplo, um User objeto retornado por vários endpoints). O uso de $ref: "#/components/schemas/User" manter o esquema DRY e gera uma única classe nomeada nos SDKs de cliente.
• Esquemas inline — Corretos para formas de resposta de uso único, específicas a um único endpoint e que não serão reutilizadas. Inserir evita poluir components/schemas com definições de uso único que tornam o esquema mais difícil de ler.

O padrão anti é definir um esquema em components/schemas e depois nunca referenciá-lo. Validadores como o Spectral podem identificar componentes não utilizados, o que muitas vezes indica um $ref que deveria referenciá-lo, mas aponta para outro lugar.

requestBody vs parameters: Onde as coisas vão erradas

No OpenAPI 3.0, corpos de requisição e parâmetros são estritamente separados:

• parameters — Para valores de caminho, consulta, cabeçalho e cookie. Cada parâmetro é um valor escalar, não um objeto complexo.
• requestBody — Para o corpo do requisição (corpo JSON, dados de formulário, uploads de arquivo). Obrigatório para operações POST/PUT/PATCH que aceitam um corpo.

O erro que atrapalha os desenvolvedores ao migrarem do 2.0: no Swagger 2.0, corpos de requisição eram parâmetros com in: body. No OpenAPI 3.0 isso é inválido — in: body não existe. Um esquema com in: body passa a análise YAML, mas falha na validação do esquema, e os geradores de código ouvem erro ou silenciosamente descartam o corpo da requisição.

Como validar seu esquema localmente

Três ferramentas sólidas de linha de comando para validação local, da mais simples até a mais completa:

swagger-cli

Validação estrutural rápida e $ref resolução. Útil para uma verificação rápida:

npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

Relata erros estruturais e caminhos quebrados. $ref Não detecta problemas semânticos ou de estilo.

Redocly CLI

Validação estrutural mais um conjunto configurável de regras. Boa rigidez padrão para esquemas de produção:

npm install -g @redocly/cli
redocly lint openapi.yaml

Detecta faltas de descrição, referências quebradas e muitos problemas semânticos de forma automática.

Spectral

O linter mais configurável. Executa o conjunto de regras do OpenAPI mais regras personalizadas que você define. Ideal para equipes que querem impor diretrizes internas de estilo de API:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

O Spectral distingue erros (que quebram o esquema) de avisos (problemas de estilo/completude), então você pode corrigir problemas bloqueantes primeiro sem ruído de regras recomendativas.

Validar no navegador sem instalar nada

Se você quer validar um esquema rapidamente — sem configurar uma linha de comando ou rodar uma build — o Validador de Esquema OpenAPI / Swagger em iotools.cloud executa totalmente no navegador. Cole seu esquema YAML ou JSON e ele relata erros estruturais, caminhos quebrados, campos obrigatórios ausentes e problemas específicos de versão entre OpenAPI 2.0, 3.0 e 3.1. $ref É útil para uma verificação rápida antes de commitar, para revisar um esquema que alguém enviou, ou para validar um esquema gerado a partir de anotações e querer fazer uma verificação preliminar antes de gerar código.

Integrar a validação ao seu fluxo de trabalho

Validação de um único uso detecta problemas imediatos, mas não previne regressões. Uma abordagem mais duradoura:

Hook pré-commit

• — Execute antes de cada commit. Um esquema quebrado nunca chega ao repositório. swagger-cli validate ou spectral lint Passo no pipeline de CI
• — Adicione a validação do esquema como um passo inicial no seu pipeline de CI, antes de qualquer etapa de geração de código ou implantação que dependa do esquema. Validação do esquema gerado
• — Se você gerar seu esquema a partir de anotações de código (por exemplo, springdoc, swagger-annotations, FastAPI), valide a saída gerada, não apenas as anotações. O passo de geração pode produzir saída inválida quando as anotações se contradizem ou estão incompletas. O objetivo é tornar impossível enviar um esquema inválido — não apenas algo que você corrige quando um consumidor relata problemas.

O objetivo é tornar uma especificação inválida impossível de entregar — não apenas algo que você corrige quando um consumidor relata problemas.

Você também pode gostar