Como migrar do Redocly para o Apidog sem perder seu fluxo de trabalho Docs-as-Code

Se você executa seu portal do desenvolvedor no Redocly, você já trabalha da maneira que a maioria das equipes de API deseja: openapi.yaml fica no Git, os guias são Markdown, e um push atualiza a documentação. O medo ao trocar de ferramenta é perder esse ciclo e acabar editando a documentação manualmente em uma interface web.

Você não precisa. O Apidog Spec-first Mode mantém sua especificação e seu Markdown no mesmo repositório, sincroniza a cada push por meio de um webhook e publica um portal com guias e uma referência de API em uma única barra lateral. Este guia percorre a migração, incluindo a única parte que não é transferida automaticamente: o conteúdo de formato longo que muitos usuários do Redocly mantêm dentro de info.description e tags[].description.

Se você ainda está comparando ferramentas, comece com Apidog vs. Redocly ou a lista mais ampla de alternativas ao Redocly. Este post pressupõe que você escolheu o Apidog e deseja migrar sem quebrar seu fluxo de trabalho.

O que é transferido e o que não é

Testamos esta migração com uma especificação de produção real: OpenAPI 3.0.3, 62 operações em 13 tags, com conteúdo de introdução, autenticação e integração escrito nos campos de descrição da especificação. Veja o que aconteceu na importação.

A referência da API é transferida sem edições. A lacuna é o conteúdo narrativo.

Por que seus campos de descrição não são renderizados da mesma forma

Redoc, o renderizador por trás dos documentos de referência do Redocly, trata info.description como um mini-documento. Cada cabeçalho Markdown dentro dele se torna uma entrada na barra lateral, então as equipes frequentemente escrevem seus guias completos de “Primeiros passos” e “Autenticação” lá. As descrições de tags são renderizadas como texto de introdução no topo de cada grupo de tags.

Essa é uma convenção do Redoc, não faz parte da Especificação OpenAPI. A especificação define apenas description como uma string CommonMark. O Apidog, como a maioria dos portais, mantém os guias como documentos Markdown independentes e mantém a especificação para a referência. Uma publicação padrão após a importação mostra apenas a referência da API, sem os guias que você escreveu nos campos de descrição.

A correção é uma movimentação única: retire esse conteúdo do YAML e coloque-o em arquivos Markdown ao lado dele. Depois disso, tudo permanece orientado pelo Git.

A estrutura do repositório de destino

Esta é a estrutura que validamos:

your-repo/
├── openapi.yaml              # source of truth for the API reference
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

openapi.yaml orienta a referência da API. Cada arquivo em docs/ se torna uma página na barra lateral do portal. As imagens referenciadas por esses arquivos Markdown podem ficar no mesmo repositório e sincronizar com eles.

Se você usou o sidebars.yaml do Redocly para ordenar sua navegação, mantenha-o como referência. Você definirá a mesma ordem uma vez nas configurações do site de documentação do Apidog.

Migração passo a passo

1. Audite o que está dentro dos seus campos de descrição

Antes de mover qualquer coisa, veja quanto conteúdo está na especificação. Com yq:

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

A lista de cabeçalhos é sua futura lista de arquivos em docs/. Em nosso teste, info.description se dividiu em dois arquivos Markdown, e as descrições de tags se tornaram páginas de introdução por pasta, mais um arquivo Markdown extra.

2. Divida info.description em arquivos Markdown

Copie cada seção de nível superior para seu próprio arquivo em docs/. Mantenha os cabeçalhos, exemplos de código e links. Em seguida, reduza info.description na especificação para um resumo de um parágrafo, para que o conteúdo fique em apenas um lugar.

Fique atento a dois recursos específicos do Redoc enquanto copia:

• <SecurityDefinitions /> e tags Redoc similares não são renderizadas fora do Redoc. Substitua-as por uma pequena seção escrita que vincule aos esquemas de segurança na referência.
• Links como #tag/Payments apontam para âncoras do Redoc. Atualize-os para os URLs correspondentes de documentos ou pastas do Apidog após a primeira publicação.

3. Conecte o repositório no Spec-first Mode

Crie um projeto no Spec-first Mode, conecte seu repositório (GitHub, GitLab, Azure DevOps ou Bitbucket), aponte-o para openapi.yaml e a pasta docs/, e instale o webhook. A partir de então, um push para o branch rastreado atualiza o projeto.

Após a primeira sincronização, o workspace Specs mostra sua especificação e o restante do repositório. A aba APIs lista as operações analisadas de openapi.yaml, Docs contém suas páginas Markdown, e All files espelha o repositório.

O webhook é o que mantém isso como um fluxo de trabalho de docs-as-code. Sem ele, você teria que acionar sincronizações manualmente. Para relembrar por que isso importa, veja nosso guia sobre documentação como código.

4. Publique o site de documentação e defina a navegação

Publique um site de documentação a partir do projeto e organize a barra lateral. A ordem que a maioria dos usuários do Redocly deseja, e a que reproduzimos, é:

1. Primeiros Passos
2. Autenticação
3. Guias de integração
4. Referência da API (as pastas de endpoint das suas tags)

Páginas Markdown e pastas de API se misturam livremente em uma árvore, então você pode corresponder de perto à sua barra lateral atual do Redocly.

5. Adicione seu domínio personalizado

Aponte um CNAME como developers.example.com para o site de documentação. Domínios personalizados estão disponíveis no plano Gratuito.

Deixe seu agente de codificação migrar descrições de tags com o Apidog CLI

As descrições de tags são a parte mais tediosa. Treze tags significam treze trabalhos de copiar e colar, e você os refará toda vez que uma descrição de tag mudar durante a transição. Entregue isso ao seu agente de codificação em vez disso.

Apidog CLI fornece ao Claude Code, Codex, Cursor ou qualquer agente de terminal acesso JSON estruturado ao seu projeto, incluindo pastas de endpoint. Configure-o uma vez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

A última linha instala a skill do Apidog para que seu agente conheça os comandos sem adivinhar. O guia de instalação cobre tokens e implantações privadas.

Em seguida, dê ao seu agente um prompt:

Leia openapi.yaml. Para cada tag com uma descrição, encontre a pasta de endpoint correspondente no projeto Apidog <PROJECT_ID> e defina a descrição dessa pasta como a descrição da tag. Valide cada payload com apidog cli-schema validate folder-update antes de escrever. Mostre-me a lista de pastas que você alterou.

Veja o que o agente executa:

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

O esquema folder-update aceita name, parentId e description, e description é suportado em pastas de endpoint e de cenário de teste. Para guias que não pertencem a uma única tag, o agente pode usar apidog doc list e apidog doc create da mesma forma, após ler apidog cli-schema get doc-create.

Para mostrar a introdução de uma pasta no site publicado, defina Folder Contents Displaying Setting nas configurações da pasta em Documentation Settings after Publication.

Um aviso honesto: exibir descrições de tags como páginas de introdução por categoria funciona, mas depende de um caminho menos documentado. Teste em duas ou três pastas em seu próprio workspace antes de depender disso para todas elas. Para mais trabalho de especificação orientado por agente, veja usando Apidog CLI no Claude Code e deixando um agente atualizar sua especificação de API.

O que fica fora do Git

Um projeto Spec-first mantém sua API e seu Markdown no Git. Algumas configurações do portal ficam na interface do Apidog e não são controladas por versão:

Esses são itens configurados uma vez. Você mexe neles quando adiciona uma nova seção de nível superior, não a cada alteração de conteúdo. O Redocly mantém mais disso em redocly.yaml e sidebars.yaml, então se você revisa alterações de navegação em pull requests hoje, planeje isso para se mover para a UI.

Plano e preços

A configuração descrita aqui se encaixa no plano Gratuito, com domínio personalizado incluído. O Gratuito cobre até 4 membros da equipe. Planos pagos adicionam coisas como vários sites de documentação por projeto e controles de visibilidade personalizados. Confira preços do Apidog para os limites atuais.

Redocly vs. Apidog após a migração

A troca é simples. Você perde a navegação definida em YAML. Você ganha testes, mocking e uma CLI amigável para agentes na mesma especificação de onde sua documentação vem. Para uma análise CLI por CLI, leia Apidog CLI vs Redocly CLI.

PERGUNTAS FREQUENTES

Meus URLs hospedados no Redocly continuarão funcionando? Não automaticamente. Os caminhos das páginas mudam. Se seu portal antigo tinha URLs de guias com alto tráfego, adicione redirecionamentos na sua camada de DNS ou proxy para as páginas principais após trocar o domínio.

Preciso reescrever minha especificação OpenAPI? Não. A especificação é importada como está. Você apenas move o conteúdo narrativo de info.description e tags[].description para arquivos Markdown.

Posso manter x-tagGroups? Use pastas para agrupamento em vez disso. Cada tag se torna uma pasta, e você pode aninhar pastas para reproduzir seus grupos de tags.

Como isso se compara a migrar do Stoplight? A forma é semelhante: especificação no Git, Markdown ao lado, sincronização por webhook. Veja como migrar do Stoplight para o Apidog se você usa ambas as ferramentas.

E se um passo se comportar de maneira diferente no meu workspace? Nossos resultados vieram de um ambiente de teste. Execute novamente a importação em um branch primeiro e compare o portal publicado com o atual antes de trocar o DNS.

Faça a mudança em uma tarde

Uma migração do Redocly para o Apidog é principalmente uma movimentação de conteúdo. Sua especificação é importada como está. Seus guias saem dos campos de descrição para uma pasta docs/ uma vez. Um webhook mantém tudo sincronizado depois disso. Deixe seu agente lidar com o trabalho repetitivo de descrição de tags com o Apidog CLI, e gaste seu próprio tempo verificando o portal publicado página por página.

Baixe o Apidog e conecte seu repositório ao Spec-first Mode para iniciar a migração.