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

Se você está migrando do Stoplight Studio ou Stoplight Platform para o Apidog, não precisa reenviar suas especificações OpenAPI. O Modo Spec-First do Apidog, atualmente em beta, conecta-se diretamente ao seu repositório GitHub ou GitLab. Assim, o Git continua sendo a fonte da verdade e o histórico de commits permanece intacto.

Experimente o Apidog hoje

Este guia mostra como migrar na prática: exportar ativos do Stoplight, mapear a estrutura de diretórios, conectar o repositório ao Apidog e substituir configurações como .stoplight.json e toc.json.

Equipes que já mantêm especificações OpenAPI no Git e usam o Stoplight para documentação podem migrar sem reestruturar todo o fluxo. Se você ainda está avaliando alternativas, veja também o post sobre as principais alternativas ao Stoplight Studio.

O que permanece igual ao migrar

A base da migração não muda:

• seus arquivos OpenAPI continuam em YAML ou JSON;
• seu repositório Git continua sendo a fonte da verdade;
• sua estratégia de branches continua a mesma;
• seus commits e PRs continuam preservados.

O Stoplight armazena especificações como arquivos versionados. O Apidog lê esses mesmos arquivos quando você conecta o repositório no Modo Spec-First.

O que muda é a camada de ferramentas sobre a especificação:

• documentação interativa;
• servidor mock;
• executor de testes;
• cliente de API;
• colaboração no workspace.

Em vez de usar Stoplight para documentação e outras ferramentas separadas para testes ou mocks, o Apidog centraliza essas etapas em um workspace sincronizado com o mesmo arquivo OpenAPI.

Na prática, a 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 configurar o Apidog, garanta que tudo que está no Stoplight também esteja salvo localmente ou no Git.

Se você usa Stoplight Studio com backend Git

Suas especificações OpenAPI, modelos JSON Schema e páginas Markdown provavelmente já estão no repositório. Primeiro, atualize sua cópia local:

git pull

O Stoplight segue a Especificação OpenAPI, então esses arquivos funcionam no Apidog sem conversão.

Uma estrutura típica pode ser assim:

your-api-repo/
  .stoplight.json          # Configuração do projeto Stoplight
  reference/
    petstore.yaml          # Especificação OpenAPI
  models/
    error.json             # Modelos JSON Schema compartilhados
  docs/
    introduction.md        # Páginas Markdown
    authentication.md
  toc.json                 # Ordem da navegação no Stoplight
  assets/
    images/
      architecture.png

Se você usa Stoplight Platform sem backend Git

Exporte os arquivos manualmente pela UI do Stoplight:

1. Abra cada projeto de API.
2. Vá até a opção de exportação.
3. Baixe o arquivo OpenAPI em YAML.
4. Copie suas páginas Markdown para uma pasta docs/.
5. Crie um novo repositório Git no GitHub ou GitLab.
6. Faça commit dos arquivos exportados.

Exemplo:

mkdir your-api-repo
cd your-api-repo

mkdir reference docs models assets

# Copie os arquivos exportados para as pastas correspondentes

git init
git add .
git commit -m "Export Stoplight API project"

Depois que seus arquivos estiverem em um repositório Git, você pode conectá-los ao Apidog.

Passo 2: Entenda o que substituir do Stoplight

Dois arquivos controlam a estrutura de projetos no Stoplight:

Arquivo Stoplight	O que ele faz	Equivalente no Apidog
.stoplight.json	Declara raiz do projeto, caminhos de especificação, documentos e arquivos incluídos	Configurações de conexão do repositório no projeto Apidog, feitas pela UI
toc.json	Controla ordem e agrupamento das páginas na sidebar do Stoplight	Estrutura e ordenação configuradas na área de documentação do Apidog
reference/	Convenção comum para arquivos OpenAPI no Stoplight	Caminho configurável no Modo Spec-First
models/	Armazena arquivos JSON Schema compartilhados	Referenciados via components/schemas e $ref na especificação OpenAPI
docs/	Armazena páginas Markdown	Importadas como páginas de documentação no Apidog

Você não precisa excluir .stoplight.json ou toc.json imediatamente. O Apidog ignora arquivos desconhecidos. Eles podem permanecer no repositório até você fazer um PR de limpeza.

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

O Modo Spec-First do Apidog vincula um repositório GitHub ou GitLab a um projeto Apidog. A especificação OpenAPI passa a ser lida diretamente do Git, não de uma cópia interna.

Fluxo recomendado:

1. No Apidog, crie um novo projeto em Modo Spec-First.
2. Autentique com GitHub ou GitLab.
3. Selecione o repositório.
4. Escolha o branch.
5. Informe o caminho da especificação OpenAPI, se ela não estiver na raiz.
6. Salve a configuração.

Você pode revisar a documentação do GitHub sobre autorização de apps de terceiros se precisar validar permissões OAuth.

Para produção, use normalmente main ou master. Para testar a migração, use um branch isolado, por exemplo:

git checkout -b migration/apidog-spec-first

Depois de salvar, o Apidog lê a especificação e gera:

• documentação interativa;
• endpoints mock;
• estrutura inicial para testes;
• visualização dos endpoints e schemas.

Se sua especificação usa $ref, mantenha os caminhos relativos corretos. Exemplo:

components:
  schemas:
    Error:
      $ref: '../models/error.json'

Se o arquivo OpenAPI estiver em reference/petstore.yaml e models/ estiver um nível acima, esse caminho será resolvido em relação ao arquivo raiz da especificação.

Para entender melhor a sincronização com GitHub, consulte o guia de sincronização de especificações OpenAPI com o GitHub.

Passo 4: Migre sua documentação Markdown

O Stoplight permite combinar referência de API e guias Markdown na mesma navegação. No Apidog, você pode importar suas páginas Markdown para a seção de documentação.

Fluxo prático:

1. Abra o projeto no Apidog.
2. Vá para Docs.
3. Use Importar > Markdown.
4. Faça upload dos arquivos em docs/ ou cole o conteúdo manualmente.
5. Organize a ordem das páginas na sidebar.

Se seus arquivos Markdown referenciam imagens locais, por exemplo:

![Arquitetura](../assets/images/architecture.png)

você tem duas opções:

1. Fazer upload das imagens para o armazenamento de arquivos do Apidog e atualizar os caminhos.
2. Hospedar as imagens em uma CDN ou URL pública e manter referências absolutas.

Exemplo com URL pública:

![Arquitetura](https://example.com/assets/images/architecture.png)

Passo 5: Substitua o servidor mock do Stoplight

O Stoplight Studio inclui um servidor mock local que lê a especificação OpenAPI e retorna respostas de exemplo. O Apidog também gera mocks a partir da especificação, mas com uma URL compartilhada em nuvem.

Se sua equipe usava algo como:

stoplight mock reference/your-api.yaml

a mudança principal é operacional: frontend, QA e outras equipes passam a usar uma URL mock compartilhada.

O Apidog gera mocks com base em:

• operações definidas no OpenAPI;
• exemplos declarados em examples;
• exemplos em example;
• schemas de resposta;
• regras configuradas por endpoint dentro do Apidog.

Exemplo de resposta com examples:

paths:
  /orders:
    post:
      responses:
        '201':
          description: Pedido criado
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              examples:
                created:
                  value:
                    id: "ord_123"
                    status: "created"

Antes de substituir o mock local, valide:

• se a URL mock pode ser acessada pela rede da empresa;
• se há necessidade de autenticação;
• se os exemplos retornados batem com o esperado pelo frontend;
• se regras específicas precisam ser configuradas por endpoint.

Passo 6: Reconstrua seus conjuntos de testes

Se você usava testes de contrato, cenários de API ou linting no Stoplight, trate cada parte separadamente.

Linting com Spectral

O Stoplight usa Spectral para linting de OpenAPI, normalmente configurado com .spectral.yaml.

O Apidog tem regras próprias de linting para conformidade com OpenAPI, mas não executa Spectral diretamente. Se sua equipe depende de regras customizadas, continue rodando Spectral no CI.

Exemplo com GitHub Actions:

name: OpenAPI lint

on:
  pull_request:
    branches: [main]

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

      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli

      - name: Lint OpenAPI spec
        run: spectral lint reference/your-api.yaml

Assim, o Apidog cuida da documentação, mocks e testes, enquanto o Spectral continua validando suas regras customizadas.

Testes de API no Apidog

O Stoplight Platform oferece testes baseados em cenários. No Apidog, você reconstrói esses fluxos no executor visual de testes.

Você pode criar cenários com:

• múltiplas requisições encadeadas;
• variáveis de ambiente;
• extração de valores de resposta;
• asserções em status code;
• validação de headers;
• validação de corpo de resposta.

Exemplo: se no Stoplight você validava que POST /orders retorna 201 e um header location, crie um caso equivalente no Apidog e execute no CI com a CLI.

# .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

Esse fluxo mantém sua estrutura atual do GitHub Actions e substitui gradualmente os testes executados pelo Stoplight.

O guia de fluxo de trabalho de API nativo do Git mostra como integrar execuções do Apidog em pipelines.

Checklist de avaliação para equipes empresariais

Antes de concluir a migração, valide as capacidades que impactam times maiores:

Capacidade	O que verificar em uma avaliação do Apidog
Acesso à documentação privada	Confirme se é possível restringir páginas a usuários autenticados ou domínios de e-mail específicos.
Reutilização de schemas entre projetos	Teste se seus components/schemas compartilhados funcionam sem cópia manual entre projetos.
Regras customizadas de lint	Verifique se o modelo de linting atende ao que hoje está em .spectral.yaml; mantenha Spectral no CI se necessário.
SSO/SCIM	Confirme suporte ao seu provedor de identidade e granularidade de provisionamento.
Logs de auditoria	Verifique quais eventos são registrados e se o formato atende aos requisitos de segurança e compliance.
URLs públicas de documentação	Planeje redirecionamentos se links externos apontam para páginas antigas do Stoplight.
Acesso ao mock server	Teste políticas de rede, autenticação e acesso por times externos.

Trate essa lista como um plano de validação. Um teste de duas semanas com uma API representativa costuma ser suficiente para identificar ajustes.

FAQ

Posso continuar usando o Spectral com o Apidog?

Sim. Execute o Spectral no seu pipeline CI de forma independente. O arquivo .spectral.yaml permanece no repositório, e o CI executa o lint em cada PR. O Apidog não entra em conflito com esse fluxo. Consulte a documentação do Spectral para opções de integração.

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

Não, desde que os caminhos estejam corretos no arquivo OpenAPI. O Apidog resolve $ref em relação à localização da especificação raiz.

Exemplo:

$ref: '../models/error.json'

Se models/ está um nível acima de reference/, o caminho será resolvido corretamente. Teste primeiro com uma especificação que use referências externas.

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

Sim. GitHub e GitLab são suportados. O fluxo é semelhante: autenticar, selecionar repositório, escolher branch e apontar para a especificação OpenAPI. Para estratégias de versionamento, veja o guia de controle de versão OpenAPI com Git.

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

URLs hospedadas no Stoplight, como docs.stoplight.io/your-org/your-api, deixam de funcionar quando a assinatura ou publicação correspondente for encerrada. O Apidog fornece uma nova URL para sua documentação. Se há links externos apontando para o Stoplight, configure redirecionamentos na camada DNS, CDN ou proxy.

Preciso excluir .stoplight.json e toc.json?

Não. O Apidog ignora arquivos desconhecidos. Você pode mantê-los durante a migração para evitar conflitos. Depois que a equipe estiver usando apenas o Apidog, remova-os em um PR de limpeza.

Conclusão

Migrar do Stoplight para o Apidog não exige recomeçar do zero. Suas especificações OpenAPI continuam no Git, seus branches continuam iguais e diretórios como reference/, models/ e docs/ podem ser reaproveitados.

O plano prático é:

1. Exportar ou sincronizar os arquivos do Stoplight.
2. Garantir que tudo esteja em um repositório Git.
3. Conectar o repositório ao Modo Spec-First do Apidog.
4. Importar a documentação Markdown.
5. Validar mocks.
6. Reconstruir testes de API no Apidog.
7. Manter Spectral no CI, se você usa regras customizadas.

Para começar, conecte seu repositório OpenAPI existente no GitHub ou GitLab ao Modo Spec-First. Sem reenvio de especificação, sem perder histórico de Git e sem mudar o fluxo de PRs da equipe. Você também pode baixar o Apidog e testar a migração com uma API representativa antes de mover todos os projetos.