Linting OpenAPI com Spectral e uma forma mais fácil

Dois engenheiros da mesma equipe lançam dois endpoints na mesma semana. Um retorna created_at, o outro retorna createdAt. Um pagina com ?page=, o outro com ?offset=. Nenhum está errado por si só. Juntos, eles fazem com que sua API pareça ter sido montada por estranhos, e todo cliente que a consome paga o preço. O arquivo OpenAPI valida perfeitamente. Ele faz o parse, renderiza no Swagger UI, gera um SDK. É apenas inconsistente, e um validador simples não tem nada a dizer sobre isso.

Essa é exatamente a lacuna que um linter preenche. Um validador responde “esta especificação é uma OpenAPI legal?” Um linter responde “esta especificação segue as regras que concordamos?” A ferramenta de código aberto mais popular para a segunda pergunta é o Spectral, o linter da Stoplight para documentos JSON e YAML. Ele vem com um conjunto de regras OpenAPI integrado, permite que você escreva suas próprias regras e roda a partir do terminal ou do seu editor. Se você quer uma maneira gratuita e programável de aplicar um guia de estilo de API, o Spectral é o primeiro passo óbvio, e este guia mostra como usá-lo corretamente.

Ele também mostra a troca. Spectral é um conjunto de regras que você monta e mantém. Para equipes que preferem obter verificações de consistência, servidores mock e testes executáveis de um só lugar sem precisar escrever regras YAML manualmente, o Apidog incorpora esse trabalho na própria superfície de design. Creditaremos o Spectral completamente primeiro, depois mostraremos onde o caminho "tudo em um" economiza a manutenção.

O que o Spectral realmente faz

Spectral é um linter genérico. Você o aponta para um documento estruturado, fornece um conjunto de regras, e ele relata todos os locais onde o documento quebra uma regra, com um número de linha e uma severidade. Não é específico do OpenAPI; ele entende OpenAPI, AsyncAPI e Arazzo de fábrica, e você pode lintar qualquer arquivo JSON ou YAML com regras personalizadas.

A razão pela qual ele é importante para o trabalho com APIs é o conjunto de regras integrado spectral:oas. Esse conjunto de regras codifica uma longa lista de convenções OpenAPI: operações devem ter um operationId, o objeto info deve conter uma descrição e contato, tags devem ser definidas antes de serem usadas, parâmetros não devem se duplicar. Execute-o contra uma especificação real e você quase sempre obterá uma lista de avisos na primeira tentativa. Nenhum deles quebra um parser. Todos eles tornam a especificação mais difícil de conviver.

Este é um trabalho diferente da validação estrutural. Uma ferramenta como swagger-cli ou Redocly responde se o documento está em conformidade com o esquema OpenAPI. O Spectral responde se o documento segue o estilo da sua empresa, além disso. Você quer ambos, e as duas verificações se combinam perfeitamente em um pipeline. Abordamos a metade da validação no guia sobre como validar especificações OpenAPI; este artigo é sobre a metade de estilo e consistência.

Instalando o Spectral e executando sua primeira lint

O Spectral é distribuído como um pacote npm. A CLI é @stoplight/spectral-cli. Instale-o globalmente:

npm install -g @stoplight/spectral-cli

Node.js é a única dependência do sistema, então qualquer máquina ou imagem de CI com Node já instalado pode executá-lo. Se você preferir não instalá-lo globalmente, npx @stoplight/spectral-cli ... funciona em executores de build efêmeros.

O Spectral precisa de um conjunto de regras para saber o que verificar. A convenção é um arquivo chamado .spectral.yaml no seu diretório de trabalho. O menor e mais útil estende as regras OpenAPI embutidas:

# .spectral.yaml
extends: ["spectral:oas"]

Agora, faça o lint de uma especificação. Com um arquivo .spectral.yaml no diretório atual, o Spectral o detecta automaticamente:

spectral lint openapi.yaml

Ou aponte explicitamente para um conjunto de regras:

spectral lint openapi.yaml --ruleset .spectral.yaml

A saída é legível propositalmente. Cada descoberta mostra a linha e coluna, a severidade, a regra que foi acionada e uma mensagem legível para humanos:

openapi.yaml
  3:6   warning  info-contact      Info object should contain `contact` object.
  5:10  error    info-description   OpenAPI object info `description` must be present.

✖ 2 problemas (1 erro, 1 aviso, 0 informações, 0 dicas)

Essa primeira execução contra uma especificação existente é o momento em que a maioria das equipes percebe o quanto de desvio se acumulou. As regras nunca foram impostas, então ninguém as seguiu.

Escrevendo suas próprias regras

O conjunto de regras embutido é um ponto de partida, não o destino. O verdadeiro valor do Spectral é codificar as convenções da sua equipe como regras que uma máquina verifica a cada alteração. Uma regra tem quatro partes: o que observar (given, uma expressão JSONPath), o que verificar (then, uma função), o quão "barulhento" ser (severity), e o que dizer quando falhar (message).

Aqui está uma regra que impõe caminhos em kebab-case, uma convenção comum da empresa:

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Paths should be kebab-case.
    message: "{{property}} should be kebab-case (lower-case, hyphen-separated)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

O given seleciona cada chave de caminho. O then executa a função pattern embutida contra uma expressão regular. Qualquer coisa que falhe no padrão é relatada como um aviso com sua mensagem. Você pode proibir IDs inteiros em favor de UUIDs, exigir uma resposta de erro em todo POST, proibir números de versão em URLs de servidor ou exigir que toda operação contenha uma descrição. O Spectral vem com várias funções principais (truthy, pattern, schema, length, enumeration e mais) para que a maioria das convenções não precise de nenhum código.

Quando uma regra precisa de lógica que uma opção de função não consegue expressar, o Spectral permite que você escreva regras em JavaScript ou TypeScript e importe funções personalizadas. É aí que a ferramenta se torna poderosa e onde a manutenção começa. Se você quiser se aprofundar, temos um guia completo sobre como construir regras personalizadas do Spectral com TypeScript.

Severidade e fazendo a build falhar

Toda regra do Spectral tem uma severidade: error, warn, info ou hint. Por padrão, a CLI só sai com um código diferente de zero quando encontra um error. Avisos são impressos, mas não fazem a execução falhar. Isso é bom enquanto você está limpando uma especificação legada e não quer que mil avisos bloqueiem cada merge.

Uma vez que sua especificação esteja limpa, aperte o cerco. O flag --fail-severity controla o limite:

spectral lint openapi.yaml --fail-severity=warn

Agora, um aviso também retorna o código de saída 1, que é o que um passo de CI lê para marcar a si mesmo como falho. Este é o mecanismo que transforma um linter em um verdadeiro portão de qualidade: o pipeline bloqueia o merge no momento em que a especificação se desvia do guia de estilo. Você também pode substituir as severidades de regras individuais em seu conjunto de regras, elevando uma regra que você se importa de warn para error ou silenciando uma que não se encaixa na sua equipe, definindo-a como off.

Executando o Spectral em CI

Um linter que só roda quando alguém se lembra não é um portão. O objetivo é executá-lo a cada push, em uma máquina limpa, com o mesmo conjunto de regras para todos. O Spectral torna isso rápido. Aqui está um job do GitHub Actions que faz o lint da especificação em qualquer pull request que a modifique:

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi.yaml --fail-severity=warn

Para relatórios mais ricos, o Spectral pode gerar XML JUnit, que a maioria dos painéis de CI analisa em uma árvore de aprovação/reprovação:

spectral lint openapi.yaml -f junit -o results.xml

Conecte esse artefato ao seu dashboard e cada colaborador verá qual regra falhou e onde, sem precisar ler logs brutos. Se você deseja ter uma visão mais ampla de como combinar verificações estruturais, linting e detecção de quebras, os padrões OpenAPI em CI se generalizam além de qualquer ferramenta única. Tratar a especificação como código é a mentalidade que faz tudo isso funcionar.

Onde o Spectral exige muito de você

O Spectral é bom no que faz. O problema honesto é que ele faz uma coisa, e o resto do ciclo de vida da especificação é seu problema para montar. Algumas realidades surgem quando uma equipe o adota além da demonstração.

Você é responsável pelo conjunto de regras. As regras spectral:oas embutidas são genéricas. Seu guia de estilo real vive em regras personalizadas que você escreve, revisa, versiona e mantém atualizadas conforme as convenções evoluem. Esse conjunto de regras se torna uma pequena base de código com sua própria carga de manutenção, e JSONPath mais funções personalizadas é uma habilidade que nem todos na equipe possuem.

Ele faz o lint do documento, não da API. O Spectral lê o arquivo. Ele não pode dizer se o serviço em execução realmente retorna o que a especificação promete. Uma especificação pode passar em todas as regras de lint e ainda descrever um endpoint que a implementação se desviou há meses. Preencher essa lacuna significa enviar solicitações reais e fazer asserções sobre as respostas, o que é uma ferramenta completamente diferente.

É uma peça de uma cadeia maior. Após o linting, você ainda precisa de mocks para equipes de frontend, um site de documentação e um conjunto de testes automatizados. Cada um é uma ferramenta separada para instalar, configurar e manter sincronizada com a especificação. O linter não sabe sobre nenhum deles, então a especificação é novamente analisada e reinterpretada em cada etapa.

Nada disso é uma crítica ao Spectral. Ele é um linter focado e honesto sobre seu escopo. Mas "focado" significa que o trabalho de integração recai sobre você.

A maneira mais fácil: consistência integrada à superfície de design

Aqui está o outro caminho. Em vez de tratar a consistência como uma etapa de linting adicionada depois que a especificação é escrita, o Apidog a trata como parte da escrita da especificação.

Apidog é uma plataforma API tudo-em-um: você projeta o esquema, depura solicitações, constrói cenários de teste, simula endpoints e publica documentação em um único espaço de trabalho. Como o design acontece dentro da ferramenta, as verificações de consistência ocorrem enquanto você digita. O designer visual aponta problemas estruturais no momento em que aparecem, da mesma forma que um compilador sublinha um erro de sintaxe, para que você os corrija antes que cheguem a um commit. Você não está executando um linter separado depois; o editor é o linter.

A maior diferença está em tudo o que vem depois. O mesmo contrato que você projeta se torna seu servidor mock, sua documentação interativa e seus cenários de teste, sem reanálise e sem uma segunda ferramenta para manter sincronizada. Quando você deseja essas verificações em um pipeline, a CLI do Apidog executa seus cenários de teste sem interface gráfica a partir do terminal e retorna um código de saída diferente de zero em caso de falha, exatamente o comportamento de gate que você esperava de um linter, exceto que ele testa a API em execução em relação ao contrato em vez de apenas ler o arquivo. Instale-o com um comando npm e aponte-o para um cenário:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli

Isso preenche a lacuna que o Spectral deixa aberta. O Spectral confirma que o documento segue seu estilo. O Apidog CLI confirma que a implementação ainda corresponde ao documento. Para a referência completa das flags, execute apidog run --help ou leia o guia completo da CLI.

Então a troca é real e vale a pena declarar claramente. O Spectral oferece um linter gratuito, programável e agnóstico de fornecedor que você monta e mantém. O Apidog oferece consistência, mocks, documentação e testes executáveis a partir de uma única fonte de verdade, com muito menos trabalho de integração. Se um passo de lint portátil em um conjunto de ferramentas existente é tudo o que você precisa, o Spectral é uma ótima resposta. Se você quer que todo o ciclo de vida funcione sem se tornar um projeto de ferramentas por si só, o caminho integrado custa menos a longo prazo.

Spectral vs Apidog em um relance

Use a tabela como um auxílio à decisão, não como um placar. A escolha certa é aquela que corresponde ao quanto do ciclo de vida você quer que uma ferramenta seja responsável.

Perguntas frequentes

O Spectral é gratuito? Sim. O Spectral é de código aberto sob a licença Apache 2.0, mantido pela Stoplight. A CLI, o conjunto de regras OpenAPI integrado e a criação de regras personalizadas são todos gratuitos para uso.

O Spectral valida se minha especificação é uma OpenAPI legal? Parcialmente. As regras integradas detectam muitos problemas estruturais, mas o Spectral é um linter, não um validador de esquema dedicado. Emparelhe-o com um validador para cobertura estrutural completa. O guia sobre validar especificações OpenAPI aborda esse lado, e as melhores ferramentas de validação OpenAPI comparam as opções.

O Spectral pode testar minha API em execução? Não. O Spectral lê apenas o arquivo de especificação. Para verificar se a API ao vivo corresponde ao contrato, você precisa de um executor que envie solicitações reais e faça asserções sobre as respostas, como a CLI do Apidog.

Como faço para que um aviso do Spectral faça minha build de CI falhar? Execute spectral lint openapi.yaml --fail-severity=warn. Por padrão, apenas a severidade error faz a build falhar; --fail-severity=warn faz com que os avisos também retornem um código de saída diferente de zero.

Qual é a diferença entre Spectral e Apidog? Spectral é um linter focado de código aberto que você configura e mantém. Apidog é uma plataforma tudo-em-um onde design, verificações de consistência, mocking, documentação e testes vivem juntos, então você monta menos e mantém menos em sincronia. Veja Apidog vs Swagger para uma comparação relacionada do cenário de ferramentas de design.

Conclusão

O Spectral resolve um problema real que os validadores simples ignoram: manter uma especificação OpenAPI consistente com as convenções que sua equipe concordou. Instale @stoplight/spectral-cli, estenda spectral:oas, adicione algumas regras personalizadas e bloqueie seu pipeline com --fail-severity=warn. Para muitas equipes, isso é suficiente e não custa nada.

O custo aparece depois, nas regras que você mantém e no resto do ciclo de vida que você constrói em torno do linter. Se você preferir obter consistência, mocks, documentação e testes executáveis a partir de uma única fonte de verdade, baixe o Apidog e construa sua especificação onde as verificações já fazem parte da superfície. De qualquer forma, o objetivo é o mesmo: uma especificação em que toda a sua equipe possa confiar, imposta por uma máquina em vez de uma esperança.