Uma especificação OpenAPI é um contrato. Geradores de código a leem, a documentação é construída a partir dela, servidores mock a executam e SDKs de cliente são produzidos a partir dela. Quando a especificação está errada, cada um desses artefatos a jusante herda o erro. Um validador detecta o problema no arquivo da especificação, antes que ele se espalhe.
Este resumo aborda as ferramentas de validação OpenAPI que valem a pena usar, para que cada uma é boa e como elas se encaixam em um fluxo de trabalho real. Algumas verificam a sintaxe bruta. Outras impõem regras de estilo e design. A melhor configuração geralmente combina ambas, e este guia explica como montá-la.
Por que validar a especificação é importante
Há dois problemas distintos que um validador resolve, e confundi-los causa confusão.
O primeiro é a correção. O arquivo é realmente um OpenAPI válido? Um bloco YAML mal-indentado, um $ref que aponta para lugar nenhum, uma resposta sem sua description obrigatória, um esquema com um erro de digitação no nome de um tipo. Estes são erros objetivos. O arquivo ou é analisado em relação ao esquema OpenAPI ou não é. Um validador de correção dá uma resposta sim ou não.
O segundo é a qualidade. A especificação é válida, mas é boa? Toda operação deve ter um resumo. Os nomes dos caminhos devem ser consistentes. Toda resposta de erro deve ser documentada. A segurança deve ser declarada. Nenhuma dessas coisas é exigida pelo esquema OpenAPI, mas ignorá-las produz uma especificação tecnicamente válida que é dolorosa de consumir. Um linter impõe essas regras de design. Detectar ambas as classes de problemas cedo é muito mais barato do que detectá-los depois que um SDK é lançado, o que é a mesma lógica por trás dos testes de contrato de API de forma mais ampla.
As ferramentas de validação que valem a pena conhecer
Swagger Editor
Swagger Editor é o editor oficial baseado em navegador do projeto OpenAPI. Você cola ou escreve sua especificação à esquerda e vê erros de validação e uma pré-visualização renderizada à direita, ao vivo. É a maneira mais rápida de verificar se uma especificação é sintaticamente válida, sem nenhuma configuração. É excelente para edição e verificações rápidas, menos adequado para execuções automatizadas em pipeline. O Swagger Editor é gratuito e roda inteiramente no navegador.
Spectral
Spectral, da Stoplight, é o linter que a maioria das equipes adota para fiscalizar a qualidade. Ele vem com conjuntos de regras para OpenAPI e AsyncAPI, e o verdadeiro valor está nas regras personalizadas. Você escreve regras em YAML ou JavaScript para impor suas próprias convenções, como exigir que toda operação tenha uma descrição ou proibir barras finais em caminhos. Ele roda a partir da linha de comando, o que o torna um ajuste natural para CI. O projeto Spectral é de código aberto.
openapi-spec-validator
openapi-spec-validator é uma ferramenta Python focada que faz um trabalho bem feito: ele verifica uma especificação contra o esquema oficial OpenAPI para as versões 2.0, 3.0 e 3.1. Ele não tem opinião sobre estilo. Ele informa se o arquivo está estruturalmente correto. Como biblioteca ou CLI, ele se encaixa perfeitamente em etapas de construção baseadas em Python e em hooks de pré-commit. Quando você deseja uma barreira de correção rígida de aprovação ou falha, esta é uma escolha clara.
Apidog
Apidog valida a especificação como parte de um fluxo de trabalho de design integrado. À medida que você constrói ou importa uma definição OpenAPI, ele sinaliza problemas estruturais no editor. Sua característica mais distintiva é a validação em tempo de execução: ele verifica as respostas da API ao vivo contra o esquema declarado em sua especificação, para que você detecte desvios onde a implementação não corresponde mais ao contrato. Isso fecha a lacuna entre um documento válido e uma API correta. Baixe o Apidog para projetar e validar especificações em uma única ferramenta.
Redocly CLI
Redocly CLI agrupa linting, validação e geração de documentação. Ele valida contra o esquema OpenAPI, oferece um conjunto de regras configurável e pode resolver especificações multifile em um único pacote. Equipes que já renderizam docs com Redoc obtêm validação na mesma cadeia de ferramentas sem adicionar outra dependência.
Vacuum
Vacuum é um linter OpenAPI rápido escrito em Go. Seu ponto de venda é a velocidade em especificações muito grandes, onde alguns linters baseados em JavaScript ficam mais lentos. É compatível com regras estilo Spectral, então uma equipe pode mudar com pouco retrabalho. Para um monorepo com uma superfície de API extensa, a diferença de desempenho é notável.
Tabela de comparação
| Ferramenta | Tipo | Verifica | Roda no CI | Melhor para |
|---|---|---|---|---|
| Swagger Editor | Editor de navegador | Sintaxe, esquema | Não | Edição ao vivo e verificações rápidas |
| Spectral | Linter CLI | Estilo, regras personalizadas | Sim | Impor convenções de design |
| openapi-spec-validator | CLI / Lib Python | Correção de esquema | Sim | Barreira rígida de aprovação/falha |
| Apidog | Plataforma integrada | Esquema + desvio em tempo de execução | Sim | Design mais validação de resposta |
| Redocly CLI | CLI | Esquema, estilo, empacotamento | Sim | Documentação e validação juntas |
| Vacuum | Linter CLI | Estilo, regras Spectral | Sim | Especificações muito grandes, velocidade |
Como montar um fluxo de trabalho de validação
Você não escolhe uma única ferramenta. Você as sobrepõe.
Comece onde você edita. Ao escrever uma especificação, use o Swagger Editor ou uma plataforma integrada para que os erros apareçam enquanto você digita. Isso detecta os erros óbvios imediatamente e é muito mais barato do que detectá-los mais tarde.
Adicione um portão de correção no CI. Execute o openapi-spec-validator ou um equivalente CLI em cada pull request que modifica a especificação. Se o arquivo não for validado contra o esquema OpenAPI, a compilação falha. Isso é inegociável e binário.
Adicione um portão de qualidade ao lado. Execute o Spectral, ou o Vacuum para especificações grandes, com um conjunto de regras que sua equipe concorda. Comece com as regras OpenAPI embutidas e, em seguida, adicione regras personalizadas para suas próprias convenções. Mantenha o conjunto de regras no controle de versão para que ele evolua com a API. Esta é a mesma disciplina que torna a automação de testes em CI/CD confiável: a verificação é executada sempre, não quando alguém se lembra.
Finalmente, valide a API em execução contra a especificação. Uma especificação pode ser perfeita enquanto a implementação se desviou dela. A validação em tempo de execução, seja através do Apidog ou de testes de contrato em sua suíte, confirma que a API ainda corresponde ao seu contrato. Para o lado dos testes, escrever asserções de API úteis aborda como verificar as respostas contra o esquema documentado.
Um erro comum: validar uma única vez
Muitas equipes validam uma especificação uma única vez, quando a escrevem pela primeira vez, e depois nunca mais. A especificação apodrece a partir daí. Um desenvolvedor adiciona um endpoint no código e esquece a especificação. Alguém ajusta o formato de uma resposta. Seis meses depois, a especificação descreve uma API que não existe mais, e os SDKs e documentos gerados estão silenciosamente errados.
A validação deve ser contínua. Conecte-a ao CI para que cada alteração na especificação seja verificada, e cada alteração na API seja verificada em relação à especificação. Trate uma falha na especificação da mesma forma que você trata um teste de unidade com falha: a compilação não passa. O princípio é o mesmo por trás dos testes automatizados em geral, que é que uma verificação só é valiosa se for executada sem que ninguém precise decidir executá-la.
Também ajuda validar contra a versão OpenAPI correta. O lançamento 3.1 alinhou o OpenAPI com o JSON Schema, o que mudou o comportamento de algumas construções de esquema. Se sua ferramenta assume 3.0, mas sua especificação declara 3.1, você pode obter resultados enganosos. A Especificação OpenAPI oficial documenta as diferenças de versão, e a maioria dos validadores permite fixar a versão explicitamente.
O que os validadores capturam que você perderia
Vale a pena ser concreto sobre os tipos de problemas que a validação identifica, porque "a especificação está errada" é muito vago para agir.
Erros estruturais são os mais fáceis de visualizar. Um $ref que aponta para um esquema que não existe. Um objeto de resposta sem description, que o OpenAPI exige. Um parâmetro de caminho declarado no template da URL, mas nunca definido na lista de parameters. Um esquema que diz type: integer enquanto o exemplo mostra uma string. Um validador de correção sinaliza cada um desses, e cada um deles, de outra forma, quebraria um gerador de código ou produziria um SDK com falha.
Questões de qualidade são mais sutis e mais comuns. Uma operação sem operationId, o que torna os nomes dos métodos do cliente gerados feios ou instáveis. Nome de caminho inconsistente, onde algumas rotas usam snake_case e outras camelCase. Endpoints que documentam uma resposta 200, mas nunca uma 400 ou 401, então os consumidores não têm ideia de como os erros se parecem. Um corpo de requisição marcado como opcional quando a API realmente o exige. Nada disso quebra um parser, mas tudo isso torna a API mais difícil de usar, e um linter é o que mantém a linha. A conexão com o comportamento real é o que o teste de contrato de API verifica uma vez que a própria especificação está limpa.
Encaixando a validação em um fluxo de trabalho "design-first"
Muitas equipes agora projetam a API antes de escrever o código, produzindo a especificação OpenAPI primeiro e gerando stubs de servidor, mocks e documentação a partir dela. A validação é ainda mais importante nesse modelo, porque a especificação não é documentação de uma API existente; é a fonte da verdade a partir da qual todo o resto é construído. Uma falha na especificação se torna uma falha no servidor gerado.
Em um fluxo "design-first", valide no momento do design. Verificações no nível do editor detectam erros à medida que a especificação toma forma, antes que qualquer geração de código seja executada. Em seguida, os gates de CI confirmam que nada regrediu. Como a especificação também impulsiona o servidor mock, uma especificação limpa significa que o mock se comporta corretamente, o que permite que as equipes de front-end e cliente construam a partir de um substituto confiável. Se você quiser ver como uma especificação alimenta o mocking, nosso guia sobre mocking de uma API para testes mostra a conexão. A disciplina compensa: cada hora gasta mantendo a especificação válida economiza várias horas de depuração de clientes incompatíveis mais tarde.
Perguntas frequentes
Qual a diferença entre um validador OpenAPI e um linter?
Um validador verifica se a especificação está estruturalmente correta em relação ao esquema OpenAPI, dando uma resposta de aprovação ou falha. Um linter verifica a qualidade e o estilo, como se cada operação tem uma descrição ou se a nomeação dos caminhos é consistente. Muitas ferramentas fazem ambos, mas respondem a perguntas diferentes, e um fluxo de trabalho robusto usa as duas.
Posso validar uma especificação OpenAPI gratuitamente?
Sim. Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI e Vacuum são todos gratuitos e de código aberto. O Apidog valida especificações em seu nível gratuito e adiciona verificações em tempo de execução. Não há razão para pular a validação por motivos de custo.
Devo validar OpenAPI 3.0 e 3.1 de forma diferente?
Você as valida com as mesmas ferramentas, mas fixa a versão. O OpenAPI 3.1 se alinhou com o JSON Schema e mudou o comportamento de alguns esquemas, então um validador que espera 3.0 pode relatar erros falsos em uma especificação 3.1. Certifique-se de que sua ferramenta suporta a versão que sua especificação declara.
Onde a validação da especificação deve ser executada?
Em dois lugares. Ao vivo em seu editor enquanto escreve a especificação, para que os erros apareçam imediatamente, e no CI em cada pull request, para que nada seja mesclado com uma especificação quebrada ou de baixa qualidade. A validação apenas no editor é fácil de ignorar; a validação no CI não é.
Como verifico se minha API corresponde à sua especificação?
A validação da especificação apenas confirma que o documento está correto, não que a implementação corresponde a ele. Para detectar desvios, execute testes de contrato ou validação em tempo de execução que comparem as respostas da API ao vivo com o esquema na especificação. O Apidog faz isso diretamente, e os frameworks de teste de contrato fazem isso em uma suíte de testes.