Como migrar do Swagger CLI para o Apidog CLI

Se você ainda executa swagger-cli validate e swagger-cli bundle em seu pipeline, você está mantendo um script em torno de uma ferramenta que ninguém mais mantém. O repositório swagger-cli no GitHub agora diz isso diretamente: o pacote não é mais mantido, o README cita o fardo de acompanhar uma enorme base de usuários que pouco contribui de volta, e ele aponta novos usuários para outro lugar.

Então, este é um bom momento para decidir onde seu fluxo de trabalho de especificação viverá a seguir. Este guia é um manual de migração, não um tutorial de uso. Se você não está pronto para migrar e apenas quer continuar usando a ferramenta antiga, o guia do Swagger CLI cobre validate e bundle em detalhes. Este artigo é sobre a mudança, especificamente como migrar do Swagger CLI para o Apidog CLI sem quebrar sua CI.

Baixe o Apidog se quiser acompanhar com comandos reais. É gratuito para começar, sem necessidade de cartão de crédito.

botão

Por que migrar agora

A resposta honesta primeiro: o swagger-cli está obsoleto e sem manutenção há algum tempo. Ele ainda funciona. Muitos pipelines o chamam hoje. Mas uma ferramenta que não receberá correções de bugs ou atualizações de especificação é uma dívida técnica em sua compilação, e os próprios mantenedores recomendam seguir em frente.

Eles apontam para um sucessor em particular. O Redocly CLI é o substituto direto mais próximo se tudo o que você sempre quis foi validar e empacotar no terminal. É de código aberto, code-first e nativo de terminal. Seu comando lint faz a validação estrutural, e redocly bundle segue os ponteiros $ref exatamente como swagger-cli bundle fazia. Se seu único objetivo é uma troca 1:1 que mantém a especificação como um arquivo plano em seu repositório, o Redocly é a escolha natural, e o Redocly publica seu próprio guia de migração com o mapeamento de comandos. Não há vergonha em seguir esse caminho.

O Apidog tem um objetivo diferente. Migre para o Apidog CLI quando quiser que a especificação faça mais do que apenas ficar em um arquivo. Em vez de validar e empacotar um documento estático, você traz toda a definição para um espaço de trabalho dinâmico, depois a valida na importação, exporta um arquivo consolidado quando precisa de um, e opcionalmente simula a API, executa cenários de teste contra ela e publica documentação da mesma fonte. O swagger-cli sempre fez apenas duas coisas. O Apidog cobre o resto do ciclo de vida.

Escolha com base na adequação, não no marketing. Se você deseja um linter e empacotador leve, configurável e que você executa puramente do terminal, o Redocly vence. Se você prefere ter uma plataforma para design, mocking, testes e documentação em vez de juntar várias ferramentas, o Apidog vence.

O que o swagger-cli fazia vs o que o Apidog CLI faz

O swagger-cli tinha exatamente dois comandos:

swagger-cli validate <arquivo> verificava um documento Swagger 2.0 ou OpenAPI 3.0 contra o esquema e verificava se seus ponteiros $ref eram resolvidos.
swagger-cli bundle <arquivo> seguia esses ponteiros $ref e combinava uma definição de múltiplos arquivos em um único arquivo, com opções para caminho de saída (-o), tipo (-t json|yaml), desreferenciação completa (-r) e indentação (-f).

Essa era a ferramenta toda. Não fazia linting com regras de estilo, gerava documentação, executava testes ou simulava nada.

O Apidog CLI mapeia esses dois trabalhos para dois de seus comandos, e então continua:

apidog import ingere uma definição em um projeto Apidog e a valida na entrada. Especificações de múltiplos arquivos têm seus ponteiros $ref resolvidos em recursos unificados automaticamente. Este é seu passo de validação, mais ingestão.
apidog export emite um único arquivo consolidado do projeto e permite que você escolha a versão OpenAPI na saída. Este é seu passo de empacotamento, mais uma atualização de versão opcional e a capacidade de emitir documentação HTML ou Markdown.
apidog run executa cenários e suítes de teste, com JUnit e outros relatores para CI. O swagger-cli não tinha equivalente.
Comandos de recursos (endpoint, schema, mock, environment, branch e mais) gerenciam o projeto a partir do terminal uma vez que a especificação está dentro.

Um ponto preciso para que o mapeamento seja honesto: o Apidog valida a estrutura na importação, mas não é um linter de guia de estilo configurável. Não há apidog lint e nem conjuntos de regras personalizados. Se você dependia de linting opinativo, essa parte não é transferida, e a seção O que você ganha aborda como lidar com isso.

O Apidog CLI é distribuído como um pacote npm. Instale-o globalmente:

npm install -g apidog-cli@latest

Em seguida, autentique-se com um token de acesso:

apidog login --with-token <TOKEN>

Você obtém o token do aplicativo ou da web do Apidog: clique em seu avatar, vá para Configurações da Conta, depois em Token de Acesso da API, e gere um. O CLI o armazena em ~/.apidog/config.toml. Trate-o como qualquer outro segredo. Não o imprima em logs ou o comite em seu repositório.

Se você deseja todas as flags e um tour mais aprofundado, o guia completo do Apidog CLI e a documentação oficial do Apidog CLI cobrem toda a superfície. Para esta migração, a instalação e o login são tudo o que você precisa para começar.

Tabela de mapeamento de comandos

Aqui está a tradução direta do swagger-cli para o Apidog CLI. A única diferença estrutural: o Apidog trabalha com base em um projeto, então a maioria dos fluxos são de importação e depois exportação, em vez de um único comando em um arquivo solto.

Comando swagger-cli	Equivalente Apidog CLI	O que muda
`swagger-cli validate openapi.yaml`	`apidog import --project <id> --format openapi --file ./openapi.yaml`	Valida a especificação na importação; especificações inválidas falham o comando
`swagger-cli bundle openapi.yaml -o out.json`	`apidog import ...` then `apidog export --project <id> --format openapi --output ./out.json`	O empacotamento se torna uma exportação do projeto; os `$refs` já resolvidos na importação
`swagger-cli bundle -t yaml`	`apidog export --project <id> --format openapi --output ./out.yaml`	O formato de saída segue o arquivo que você escreve
(sem equivalente)	`apidog export --project <id> --format openapi --output ./out.json --oas-version 3.1`	Atualiza uma especificação 2.0 ou 3.0 para 3.1 na exportação
(sem equivalente)	`apidog export --project <id> --format html --output ./docs.html`	Emite documentação HTML autônoma
(sem equivalente)	`apidog export --project <id> --format markdown --output ./docs.md`	Emite documentação Markdown
(sem equivalente)	`apidog run --project <id> -t <scenarioId> -e <envId> -r junit`	Executa testes de API na CI

As duas células que mais importam para a migração são as duas primeiras linhas. Tudo abaixo delas são capacidades que o swagger-cli nunca teve. A flag --oas-version é a atualização mais clara: o swagger-cli podia empacotar um arquivo Swagger 2.0, mas não conseguia transformá-lo em OpenAPI 3.1. O Apidog pode, na exportação, o que é útil quando você está modernizando um contrato antigo. Se seu objetivo é especificamente a saída de documentação, exportar OpenAPI para Markdown explica esse formato em mais detalhes.

Migração passo a passo

Aqui está o caminho completo de uma configuração swagger-cli para um fluxo de trabalho Apidog.

1. Obtenha o ID do seu projeto. Crie ou abra um projeto no aplicativo Apidog. O ID do projeto aparece nas configurações do projeto e na URL. Você o passará para cada comando CLI via --project.

2. Importe a especificação raiz. Aponte o Apidog para o arquivo de entrada da sua definição. Especificações multi-arquivo com ponteiros $ref são resolvidas automaticamente, então você importa a raiz e o Apidog puxa o restante:

apidog import --project 123456 --format openapi --file ./openapi.yaml

Se a especificação estiver malformada ou um $ref estiver pendente, a importação falha. Essa falha é seu portão de validação, o mesmo trabalho que o swagger-cli validate costumava fazer, agora incorporado à ingestão.

3. Verifique no aplicativo. Abra o projeto e confirme se seus endpoints, schemas e parâmetros foram importados corretamente. Essa verificação visual não tem equivalente no swagger-cli, e vale a pena fazer uma vez durante a migração para confirmar que a importação fez o que você esperava.

4. Exporte o arquivo consolidado. Quando precisar de um único arquivo plano (para uma ferramenta downstream, um gerador de cliente ou um artefato), exporte-o. Escolha a versão OpenAPI que você deseja:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Isso substitui o swagger-cli bundle. Os ponteiros $ref já foram resolvidos na importação, então a exportação é sua saída consolidada de arquivo único.

5. Conecte-o à CI. Substitua seu antigo passo swagger-cli por importação (validação na ingestão) e exportação (empacotamento), e adicione uma execução de teste se tiver cenários. A próxima seção tem um exemplo completo de GitHub Actions.

Exemplo de CI com GitHub Actions

Este workflow instala o CLI, faz login com um token dos segredos do repositório, importa a especificação para validá-la, exporta um artefato consolidado e, em seguida, executa cenários de teste com o relator JUnit para que um teste com falha falhe na verificação e barre o PR.

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

Armazene o token como APIDOG_ACCESS_TOKEN nos segredos do seu repositório para que ele nunca apareça nos logs. O relator -r "cli,junit" escreve um arquivo XML JUnit que sua CI pode exibir como um relatório de teste, e um cenário com falha retorna um código de saída diferente de zero que bloqueia o merge. Para padrões de pipeline mais aprofundados, consulte o guia CI/CD do Apidog CLI, e para configuração específica do runner, o passo a passo Apidog CLI com GitHub Actions.

O que você ganha além de validar e empacotar

É aqui que a migração compensa, e onde ser honesto é o mais importante.

Servidores de mock. Uma vez que sua especificação esteja em um projeto, o Apidog pode servir respostas mock a partir dela. Você pode desenvolver um frontend contra a API antes que o backend exista. O swagger-cli nunca tocou no comportamento em tempo de execução.

Cenários de teste automatizados. apidog run executa requisições reais contra uma API em execução e faz asserções nas respostas. Você constrói cenários visualmente no aplicativo, e depois os executa sem interface gráfica na CI. Isso preenche a lacuna que o swagger-cli deixou aberta: uma especificação válida diz que o contrato está bem formado, não que a implementação corresponde a ele.

Documentação hospedada e exportada. apidog export --format html ou --format markdown produz documentação diretamente da mesma fonte. Nenhum passo de construção de documentação separado para manter.

Agora, o limite honesto. O Apidog CLI não possui um linter de guia de estilo configurável e code-first com conjuntos de regras personalizados. Ele valida a estrutura na importação, mas você não pode criar regras no estilo Spectral ou Redocly através do CLI, e não há comando apidog lint. Se sua configuração antiga dependia de linting pesado (nomenclatura consistente, descrições obrigatórias, exemplos em cada resposta), mantenha um linter dedicado em uso. Combine o Apidog com Spectral ou Redocly para isso, e execute-o como um passo de CI separado. O guia de configuração do linter OpenAPI aborda como integrá-lo. Usar ambos não é uma contradição: faça linting com uma ferramenta especializada, depois gerencie o ciclo de vida no Apidog.