Como Migrar de Stoplight para Apidog (Fluxo de Trabalho Spec-First)

Se você está migrando do Stoplight Studio ou Stoplight Platform para o Apidog, a primeira coisa a saber é que você não precisa reenviar suas especificações OpenAPI. O Modo Spec-First do Apidog (atualmente em beta) se conecta diretamente ao seu repositório existente no GitHub ou GitLab, para que o Git permaneça a fonte da verdade e seu histórico de commits permaneça intacto. Este guia aborda cada etapa: exportar sua configuração Stoplight, mapear suas convenções de diretório para as expectativas do Apidog, e substituir .stoplight.json e toc.json pelos seus equivalentes no Apidog.

Equipes como as do Fórum Econômico Mundial já gerenciam especificações OpenAPI no Git juntamente com o Stoplight para documentação. Se essa é a sua configuração, este guia foi escrito para você. E se você ainda está ponderando opções em vez de se comprometer com uma migração, o post sobre as principais alternativas ao Stoplight Studio abrange o cenário mais amplo.

O que permanece igual ao migrar

Seus arquivos OpenAPI, seu repositório Git e sua estratégia de ramificação não mudam. Essa é a premissa chave. O Stoplight armazena especificações como arquivos YAML ou JSON controlados por versão. O Apidog lê esses mesmos arquivos quando você conecta um repositório no Modo Spec-First.

O que muda é tudo o que está sobreposto: o renderizador de documentação, o servidor mock, o executor de testes e o cliente de API. Em vez de o Stoplight Platform servir a documentação e o Postman lidar com os testes como uma ferramenta separada, o Apidog combina tudo isso em um único espaço de trabalho, sincronizado com o mesmo arquivo OpenAPI que seus engenheiros já estão commitando.

O resultado prático: sua migração é principalmente uma troca de configuração, não uma migração de dados.

Passo 1: Exporte os ativos do seu projeto Stoplight

Antes de mexer no Apidog, capture tudo o que o Stoplight possui e que ainda não está no Git.

Se você usa o Stoplight Studio com um backend Git:

Suas especificações OpenAPI, modelos JSON Schema e documentação Markdown já estão commitados. Execute um git pull para garantir que sua cópia local esteja atualizada. O Stoplight segue o formato da Especificação OpenAPI, e esses arquivos de especificação funcionam no Apidog sem conversão. A estrutura do seu repositório provavelmente se parece com isto:

your-api-repo/
  .stoplight.json          # Project config (needs replacement)
  reference/
    petstore.yaml          # Your OpenAPI spec(s)
  models/
    error.json             # Shared JSON Schema models
  docs/
    introduction.md        # Markdown guide pages
    authentication.md
  toc.json                 # Table-of-contents order (needs replacement)
  assets/
    images/
      architecture.png

Se você usa o Stoplight Platform (hospedado na nuvem, sem backend Git):

Exporte suas especificações da UI do Stoplight: abra cada projeto de API, vá para “Exportar” e baixe o OpenAPI YAML. Para documentos Markdown, copie-os para uma pasta docs/ em um novo repositório Git. O Stoplight não oferece uma exportação em massa para projetos não-Git, então faça isso por projeto de API.

Assim que seus arquivos estiverem em um repositório Git (GitHub ou GitLab), prossiga para a próxima etapa.

Passo 2: Entenda os arquivos de configuração que você está substituindo

Dois arquivos específicos do Stoplight impulsionam a estrutura do projeto. Nenhum deles tem um equivalente direto no Apidog, mas entender o que eles fazem informa exatamente o que configurar no Apidog.

A principal ideia: .stoplight.json e toc.json são proprietários do Stoplight. Você pode deixá-los no repositório (o Apidog ignora arquivos desconhecidos), mas eles não acionarão nada no Apidog. Você configura as configurações equivalentes através da UI do projeto Apidog.

Passo 3: Conecte seu repositório ao Modo Spec-First do Apidog

O Modo Spec-First do Apidog é como você vincula um repositório GitHub ou GitLab a um projeto Apidog para que a especificação OpenAPI seja sempre lida do Git, e não de um banco de dados interno do Apidog. Isso mantém o Git como a fonte autoritária e significa que seus engenheiros podem continuar enviando PRs para atualizar a especificação exatamente como fazem hoje.

Aqui está o fluxo de conexão. Você também pode revisar a documentação do GitHub sobre como conectar aplicativos de terceiros a repositórios se estiver incerto sobre a concessão de permissão OAuth.

1. No Apidog, crie um novo projeto Modo Spec-First
2. Autentique o Apidog com sua conta GitHub ou GitLab e selecione o repositório.

3.Defina o branch: use seu branch padrão (main ou master) para especificações de produção, ou um branch de feature durante o teste de migração.

1. Salve. O Apidog lê a especificação e constrói a documentação interativa, os endpoints do servidor mock e a estrutura de teste a partir dela.

Se sua especificação usa $ref para puxar esquemas do diretório models/, o Apidog resolve essas referências em relação à localização do arquivo de especificação. Nenhuma configuração extra é necessária, desde que os caminhos em seu arquivo OpenAPI estejam corretos. Para uma visão mais aprofundada de como essa sincronização Git funciona, o guia de sincronização de especificações OpenAPI com o GitHub aborda a mecânica em detalhes.

Passo 4: Migre sua documentação Markdown

O Stoplight permite misturar páginas de guia Markdown com documentos de referência de API em uma única barra lateral. O Apidog faz o mesmo através de seu editor de documentação.

Depois de conectar seu repositório, importe seus arquivos Markdown de docs/:

1. No projeto Apidog, abra a seção Docs.
2. Use Importar > Markdown e faça o upload de seus arquivos, ou cole o conteúdo página por página.

Para ativos de imagem referenciados em seu Markdown (a pasta assets/images/ em um layout típico do Stoplight), faça o upload para o armazenamento de arquivos do Apidog e atualize as referências ![alt](path) em cada página. Se suas imagens já estiverem hospedadas em uma CDN ou URL pública, você não precisa mudar nada.

Passo 5: Substitua o servidor mock do Stoplight

O Stoplight Studio inclui um servidor mock local que lê sua especificação OpenAPI e retorna respostas de exemplo. O servidor mock do Apidog faz o mesmo, mas é hospedado na nuvem e acessível a toda a sua equipe sem a necessidade de executar um processo local.

Uma vez que sua especificação esteja conectada via Modo Spec-First, o Apidog gera automaticamente endpoints mock para cada operação definida em seu arquivo OpenAPI. As respostas de exemplo vêm do campo examples em sua especificação, ou do mecanismo mock inteligente do Apidog se nenhum exemplo for definido. Você pode substituir as regras de resposta por endpoint dentro do Apidog sem tocar no arquivo de especificação.

Para uma equipe acostumada a executar stoplight mock reference/your-api.yaml localmente, a mudança é que seus engenheiros de QA e desenvolvedores frontend agora acessam uma URL de nuvem compartilhada. Isso vale a pena validar em um teste para confirmar se ele se encaixa nas suas políticas de acesso à rede.

Passo 6: Reconstrua seus conjuntos de testes

Se você usou os testes de contrato ou regras Spectral do Stoplight para linting, eles precisam de tratamento separado.

Regras de lint do Spectral: O Stoplight usa o Spectral para linting de OpenAPI, configurado via um arquivo .spectral.yaml. O Apidog possui suas próprias regras de linting integradas para conformidade com OpenAPI, mas não executa o Spectral diretamente. Se você tem regras Spectral personalizadas nas quais sua equipe confia, continue executando-as em CI (GitHub Actions ou GitLab CI) independentemente do Apidog. A cobertura de linting do Apidog e a possibilidade de compartilhar conjuntos de regras de linting personalizados entre projetos valem a pena verificar em um teste contra seus requisitos de regras específicas.

Testes de API: O Stoplight Platform inclui testes de API baseados em cenários. O executor de testes do Apidog permite que você construa cenários de teste visualmente, encadeie requisições e execute asserções contra corpo de resposta, cabeçalhos e códigos de status. Você os reconstruirá dentro do Apidog; não há importação automatizada de projetos de teste do Stoplight. O guia de fluxo de trabalho de API nativo do Git mostra como integrar execuções de teste do Apidog em um pipeline do GitHub Actions.

Um exemplo prático: se o seu teste Stoplight verificou que POST /orders retorna um 201 com um cabeçalho location, aqui está a configuração de teste Apidog equivalente em um pipeline CI usando a CLI do Apidog:

# .github/workflows/api-tests.yml
name: API contract tests

on:
  pull_request:
    branches: [main]

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

      - name: Run Apidog tests
        run: |
          npx apidog-cli run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
            --env production \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}

      - name: Publish test results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml

Isso substitui uma execução de teste do Stoplight em CI e mantém sua estrutura existente do GitHub Actions intacta.

Lista de verificação de avaliação para equipes empresariais

Se você está migrando para uma equipe maior (do tipo que avalia o Stoplight Platform em vez do Studio), existem capacidades específicas que valem a pena verificar antes de se comprometer. O Apidog cobre essas áreas, mas o comportamento exato depende do seu plano e da configuração do seu espaço de trabalho.

Enquadre-os como tarefas de avaliação, não como bloqueadores. A maioria pode ser confirmada em um teste de duas semanas com um projeto representativo.

FAQ

Posso continuar usando o Spectral com o Apidog?

Sim. Execute o Spectral em seu pipeline CI independentemente do Apidog. Seu arquivo .spectral.yaml permanece no repositório, e sua tarefa de CI (GitHub Actions, GitLab CI) executa o lint no arquivo OpenAPI em cada PR. O Apidog lida com documentação, mocking e testes; o Spectral lida com linting. Eles não entram em conflito. Consulte a documentação do Spectral para opções de integração CI.

Meus caminhos $ref serão quebrados ao conectar o repositório ao Apidog?

Não, se seus caminhos estiverem corretos no arquivo de especificação. O Apidog resolve $ref em relação à localização do arquivo OpenAPI raiz. Se sua especificação disser $ref: '../models/error.json' e a pasta models/ estiver um nível acima de reference/, o Apidog seguirá esse caminho relativo no repositório. Teste primeiro com uma especificação que use refs externas.

O Modo Spec-First do Apidog suporta GitLab e GitHub?

Sim, tanto GitHub quanto GitLab são suportados. O fluxo de conexão é o mesmo; você se autentica com sua conta GitLab e seleciona o repositório e o branch. Para mais opções de controle de versão, o guia de controle de versão OpenAPI com Git aborda as estratégias de branch em detalhes.

O que acontece com minha URL de documentação Stoplight existente após a migração?

As URLs de documentação hospedadas no Stoplight (docs.stoplight.io/your-org/your-api) param de funcionar assim que você cancela sua assinatura Stoplight. O Apidog fornece à sua documentação uma nova URL em um subdomínio que você configura. Configure redirecionamentos na camada DNS ou CDN se você tiver links externos apontando para suas páginas de documentação Stoplight.

Preciso excluir .stoplight.json e toc.json do repositório?

Não. O Apidog ignora arquivos que não reconhece. Deixe-os no lugar se a remoção deles causar conflitos de mesclagem ou confusão. Assim que a equipe estiver totalmente no Apidog, você pode excluí-los em um PR de limpeza, mas isso não é necessário para que a migração funcione.

Conclusão

Migrar do Stoplight para o Apidog não significa começar do zero. Suas especificações OpenAPI permanecem no Git, seu fluxo de trabalho de branch permanece intacto, e a estrutura de diretórios reference/, models/ e docs/ se mapeia perfeitamente para o que o Apidog espera. A migração é uma troca de configuração: substitua .stoplight.json e toc.json pelas configurações do projeto Apidog, conecte seu repositório através do Modo Spec-First e reconstrua seus cenários de teste dentro do executor de testes do Apidog.

Inicie sua migração do Stoplight conectando o Modo Spec-First do Apidog ao seu repositório OpenAPI existente no GitHub ou GitLab. Sem reenvio, sem bloqueio, o mesmo histórico do Git. Baixe o Apidog para começar, e use um projeto de API representativo para sua avaliação para revisar a lista de verificação acima com seus dados reais.