Um arquivo Swagger quebrado raramente se anuncia. O YAML analisa corretamente. A página de documentação é renderizada. Então um desenvolvedor front-end gera um cliente a partir da sua especificação, a compilação falha em um campo `required` ausente, e você descobre que sua descrição de API "finalizada" tinha um erro de digitação em um `$ref` três commits atrás. A especificação estava errada o tempo todo. Nada te avisou até que custou uma tarde a alguém.
Esse é o trabalho que um validador Swagger faz: ele lê seu arquivo OpenAPI ou Swagger e te diz, antes que alguém o consuma, se o documento é realmente válido. Não "parece certo", mas "está em conformidade com a Especificação OpenAPI, resolve todas as referências e descreve um esquema em que uma ferramenta pode confiar". Um validador transforma bugs estruturais silenciosos em erros ruidosos e numerados por linha que você corrige em segundos, em vez de depurar por horas em etapas posteriores.
O que um validador Swagger realmente verifica
Primeiro, a nomenclatura. "Swagger" e "OpenAPI" descrevem a mesma coisa em diferentes pontos da história. O formato foi chamado Swagger até a versão 2.0, depois doado à OpenAPI Initiative e renomeado; 3.0, 3.1 e 3.2 são todos OpenAPI. As pessoas ainda dizem "validador Swagger" por hábito, e a maioria das ferramentas aceita tanto Swagger 2.0 quanto OpenAPI 3.x. Se o histórico de versões for confuso, o detalhamento Swagger vs OpenAPI esclarece. Para as diferenças entre as versões recentes, veja o que mudou em OpenAPI 3.2 vs 3.1 vs 3.0.
Um validador real executa três tarefas, em ordem:
- Analisar (Parse). O arquivo é mesmo um YAML ou JSON válido? Uma tabulação perdida, uma chave duplicada, um colchete não fechado, o documento nunca carrega. Este é o erro mais barato de capturar e o mais embaraçoso de enviar.
- Validar a estrutura. O documento está em conformidade com o esquema OpenAPI? Toda operação precisa de um objeto `responses`. Todo parâmetro precisa de um valor `in`. Um `$ref` precisa apontar para algo que existe. É aqui que a maioria dos bugs reais se esconde.
- Resolver referências. Os documentos OpenAPI estão cheios de ponteiros `$ref` que unem esquemas reutilizáveis. Um validador segue cada um deles e falha se um destino estiver ausente, for circular de uma forma que a especificação proíba, ou apontar para o arquivo errado.
Passe por todos os três e você terá um documento que qualquer ferramenta compatível, gerador de código, servidor mock, renderizador de documentos, pode ler sem engasgar. Falhe em qualquer um e a falha aparecerá em algum lugar menos conveniente do que seu terminal.
Os erros que ele captura que causam problemas mais tarde
A validação parece abstrata até que você veja o que passa despercebido sem ela. Estes são os erros de especificação que parecem inofensivos no editor e se transformam em incidentes reais a jusante.
Ponteiros `$ref` quebrados. Você renomeia um esquema de `User` para `UserProfile`, mas perde uma referência profunda no corpo de uma resposta. O YAML ainda analisa. A documentação ainda renderiza o resto da página. O gerador de código encontra o ponteiro solto e emite um cliente com um tipo ausente, ou simplesmente trava. Um validador sinaliza o `$ref` quebrado no momento em que você salva.
Divergência entre esquema e exemplo. Seu esquema diz que `age` é um inteiro; seu exemplo mostra `"age": "thirty"`. O Swagger UI exibe ambos alegremente. Um servidor mock construído a partir da especificação então retorna uma string onde os consumidores esperam um número, e um teste de contrato a três equipes de distância fica vermelho por razões que ninguém consegue rastrear até o seu arquivo.
Peças `required` ausentes. Uma operação sem `responses`. Um parâmetro de caminho declarado no template da URL, mas nunca definido em `parameters`. Um `requestBody` sem `content`. Cada um é tecnicamente um documento malformado, e cada um produz um sintoma diferente a jusante, dependendo de qual ferramenta lê a especificação primeiro.
Desvio de tipo e formato. `format: date-time` em um campo que seu backend retorna como um timestamp Unix. `type: string` em algo que é na verdade um array. Estes passam na validação estrutural, mas quebram o contrato entre a especificação e a API em execução, o que é um problema separado que abordaremos.
O padrão é consistente: um erro de especificação é invisível no momento em que você o comete e caro no momento em que outra pessoa o consome. A validação transfere o custo de volta para onde é barato.
Como validar um arquivo Swagger manualmente
Você não precisa de uma plataforma para começar. Existem três maneiras rápidas de validar uma especificação hoje.
O Swagger Editor. Cole seu YAML no Swagger Editor e ele valida enquanto você digita, sublinhando erros com números de linha na margem direita. É a maneira mais rápida de verificar a sanidade de um único arquivo, e é grátis. O limite é que é uma única caixa de texto: ele valida o documento, mas não faz nada sobre se sua API real ainda corresponde a ele, e você está escrevendo YAML manualmente sem um construtor de esquema visual. Para aprender o formato, isso é bom. Para uma especificação da qual uma equipe depende, é uma aba em um fluxo de trabalho que precisa de várias.
Um linter como o Spectral. O Spectral da Stoplight é um CLI de código aberto que vai além da validade bruta para regras de estilo. Ele verifica a validade estrutural e permite que você aplique um conjunto de regras: toda operação precisa de uma descrição, toda propriedade de esquema precisa de um tipo, a nomenclatura segue sua convenção. O Spectral é genuinamente a melhor ferramenta da categoria para governar o estilo da especificação em muitos arquivos, e se o design de API consistente é sua preocupação, vale a pena adotá-lo. Você o executa assim:
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
A desvantagem é o escopo. O Spectral valida e analisa o documento. Não é um executor de requisições; não dirá se a API que a especificação descreve realmente se comporta da maneira que a especificação afirma. Essa é uma camada diferente, e é a camada onde a maioria das surpresas de produção reside.
Um endpoint validador online. O projeto Swagger publica um serviço validador que retorna um selo de aprovação ou reprovação para uma URL de especificação hospedada. É útil para um selo de README, menos para um ciclo de correção interativo. Para uma cobertura mais profunda de opções autônomas, mantemos um resumo das melhores ferramentas de validação OpenAPI e um passo a passo focado sobre como validar especificações OpenAPI.
Todos os três validam o documento. Nenhum deles fecha a lacuna entre uma especificação válida e uma API correta. Essa lacuna é onde a próxima seção se encaixa.
Onde o Apidog se encaixa: valide a especificação e então prove que a API corresponde a ela
Apidog é uma plataforma de API tudo-em-um: você projeta o esquema, depura requisições, constrói cenários de teste automatizados, simula endpoints e publica documentação em um único espaço de trabalho. A validação da especificação não é uma ferramenta separada que você acopla; é uma propriedade de trabalhar na plataforma.
Quando você importa um arquivo Swagger ou OpenAPI, ou o projeta no editor visual, o Apidog o analisa e valida na entrada. Um documento malformado, um `$ref` quebrado, um parâmetro sem tipo, tudo isso aparece enquanto você trabalha, não três ferramentas depois. Como o editor é visual, toda uma categoria de erros de YAML escritos manualmente nunca acontece: você não pode esquecer o valor `in` em um parâmetro quando o campo é um dropdown obrigatório. A especificação é válida por construção.
Isso cuida do documento. O problema mais difícil é a deriva, o lento desacordo entre uma especificação que diz uma coisa e uma API que faz outra. Um validador autônomo não consegue capturar isso, porque o arquivo é válido; é o serviço em execução que está errado. Este é o modo de falha por trás de tantas documentações Swagger e coleções Postman que se desviam.
Apidog fecha isso fazendo da especificação a fonte da verdade para testes. Você gera cenários de teste diretamente da sua especificação OpenAPI e, em seguida, afirma que as respostas reais correspondem ao esquema que você declarou. Quando a especificação diz que `age` é um inteiro e a API retorna uma string, o teste falha, e falha contra a especificação, não contra uma cópia mantida manualmente. A questão do validador torna-se contínua: não "este arquivo era válido quando o salvei", mas "a API em produção ainda é fiel ao seu contrato neste exato momento". Se você quer a mecânica de asserção, asserções de API: um guia prático aborda a validação da forma, status e campos da resposta.
Para equipes que desejam validação imposta automaticamente em vez de lembrada, o Apidog também cobre a manutenção da conformidade de APIs com os padrões OpenAPI como parte do ciclo de design.
Execute a validação orientada por especificação em CI com o CLI do Apidog
Um validador que só funciona quando alguém abre o editor é um validador que eventualmente é ignorado. A solução é colocar a validação no pipeline, onde ela é executada em cada push sem intervenção humana. Para isso serve o Apidog command-line runner.
O CLI é um pacote npm chamado `apidog-cli`. Ele executa os cenários de teste que você construiu no Apidog, sem interface gráfica, de qualquer ambiente com Node.js. Instale-o com um comando:
npm install -g @apidog/cli
Em seguida, execute um cenário salvo, o mesmo cenário que afirma que suas respostas ao vivo correspondem à especificação, contra um ambiente:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Algumas notas sobre o que essas flags fazem. `-t` é o ID do cenário de teste. `-e` é o ID do ambiente, para que você possa apontar as mesmas verificações para o ambiente de staging em um pull request e para produção após a implantação. `-r` escolhe os formatos de relatório: `cli` para saída de log de build legível, e você pode adicionar `html`, `json` ou `junit` para alimentar um dashboard de CI. O `--access-token` pertence a um segredo de CI, nunca em linha. Você gera tanto o token quanto o comando pronto na aba CI/CD do cenário dentro do Apidog. Para a superfície completa das flags, execute `apidog run --help` ou leia o guia completo do Apidog CLI.
O detalhe que torna isso um verdadeiro portão: o CLI sai com um código de status diferente de zero quando uma asserção falha. Sistemas de CI leem esse código de saída. Uma verificação de esquema com falha falha a etapa, que falha o trabalho, que bloqueia a mesclagem. Assim, no momento em que sua API deixa de corresponder ao seu contrato OpenAPI, a build fica vermelha, antes que a alteração seja enviada, não depois que um consumidor registra um ticket. Essa é a diferença entre validar um arquivo uma vez e validar o contrato em cada commit. O mesmo comportamento de código de saída é o motivo pelo qual o executor se encaixa em qualquer plataforma de CI, muito parecido com executar coleções Postman em CI sem Newman.
Baixe o Apidog se você deseja validação de especificação e teste de contrato no mesmo lugar onde sua equipe já projeta a API.
Um fluxo de trabalho de validação prático
Juntando as peças, aqui está uma sequência que captura erros de especificação em cada estágio, em vez de apenas no último:
- Projete ou importe em um editor de validação. Seja importando um arquivo Swagger existente ou construindo-o no designer visual do Apidog, o documento é analisado e validado estruturalmente na entrada. Referências quebradas e tipos ausentes aparecem imediatamente.
- Verifique o estilo com um linter, se você tiver um conjunto de regras. Se sua organização impõe regras de nomenclatura e descrição, execute o Spectral como uma verificação rápida antes do commit. Validade e estilo da casa são preocupações diferentes; cubra ambas.
- Gere testes a partir da especificação. Transforme o documento OpenAPI em cenários de teste para que suas asserções estejam vinculadas à mesma definição que você envia, não a uma cópia separada que se desvia.
- Proteja cada push com o CLI. Conecte `apidog run` ao seu pipeline para que uma incompatibilidade entre especificação e realidade falhe a build automaticamente.
- Trate a especificação como a fonte da verdade. Quando o design muda, os testes apontam para o mesmo arquivo, então não há nada para manter sincronizado manualmente.
As etapas 1 e 2 validam o documento. As etapas 3 a 5 validam o contrato. Você precisa de ambos, e o lugar mais barato para fazer todos eles é um único espaço de trabalho, em vez de quatro abas do navegador.
A versão resumida
Um validador Swagger captura os bugs estruturais, referências quebradas, tipos ausentes e YAML malformado, que são invisíveis quando você os escreve e caros quando outra pessoa os lê. Validar o documento é o piso, não o teto. Os erros que realmente chegam à produção são aqueles em que uma especificação válida deixa de corresponder silenciosamente a uma API em mudança, e nenhum validador em nível de arquivo pode ver isso.
A solução é validar em duas camadas e colocar ambas em um só lugar: validar o documento enquanto você o projeta e, em seguida, validar o contrato em cada push, afirmando as respostas reais em relação à especificação. O Apidog faz o primeiro por construção e o segundo através de cenários que o executor `apidog-cli` protege no CI. A especificação permanece a fonte da verdade, a build fica vermelha no momento em que a realidade se desvia dela, e um arquivo Swagger quebrado deixa de ser algo que você descobre uma tarde tarde demais.