RedoclyからApidogへの移行方法：Docs-as-Codeワークフローを失わないために

Redoclyで開発者ポータルを運用しているなら、あなたはすでにほとんどのAPIチームが望むやり方で仕事をしています。openapi.yamlはGitにあり、ガイドはMarkdownで、プッシュすればドキュメントが更新されます。ツールを乗り換えるときに恐れるのは、そのループを失い、Web UIで手作業でドキュメントを編集することになるのではないかということです。

そうする必要はありません。ApidogのSpec-firstモードは、スペックとMarkdownを同じリポジトリに保ち、Webhook経由で毎回のプッシュ時に同期し、ガイドとAPIリファレンスを1つのサイドバーにまとめたポータルを公開します。このガイドでは移行手順を順を追って説明します。自動では引き継がれない唯一の部分、つまり多くのRedoclyユーザーがinfo.descriptionやtags[].descriptionの中に保持している長文コンテンツについても扱います。

まだツールを比較している段階なら、まずApidog vs. Redoclyや、より広範なRedoclyの代替ツールのリストをご覧ください。この記事は、あなたがApidogを選び、ワークフローを壊さずに移行したいと考えていることを前提としています。

引き継がれるものと、そうでないもの

私たちは実際の本番スペックでこの移行を検証しました。OpenAPI 3.0.3、13個のタグにまたがる62個のオペレーション、そしてスペックのdescriptionフィールドに書かれたgetting-started、authentication、integrationのコンテンツを含むものです。インポート時に何が起きたかを以下に示します。

APIリファレンスは編集なしでそのまま移行されます。ギャップとなるのはナラティブコンテンツです。

descriptionフィールドが同じようにレンダリングされない理由

Redoclyのリファレンスドキュメントの背後にあるレンダラーであるRedocは、info.descriptionをミニドキュメントとして扱います。その中のすべてのMarkdown見出しがサイドバーエントリになるため、チームは「Getting started」と「Authentication」のガイド全体をそこに書くことがよくあります。タグのdescriptionは、各タググループの上部にイントロテキストとしてレンダリングされます。

これはRedocの慣習であり、OpenAPI Specificationの一部ではありません。スペックはdescriptionをCommonMark文字列として定義しているだけです。Apidogはほとんどのポータルと同様に、ガイドを独立したMarkdownドキュメントとして保持し、リファレンス用にスペックを保持します。インポート後のデフォルト公開では、APIリファレンスのみが表示され、descriptionフィールドに書いたガイドは表示されません。

解決策は一度きりの移動です。そのコンテンツをYAMLから取り出し、隣接するMarkdownファイルに移します。その後はすべてGitドリブンのままです。

移行先のリポジトリ構成

これが私たちが検証した構成です。

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

openapi.yamlがAPIリファレンスを駆動します。docs/内の各ファイルはポータルサイドバーのページになります。それらのMarkdownファイルから参照される画像は、同じリポジトリに置いて一緒に同期できます。

ナビゲーションの順序付けにRedoclyのsidebars.yamlを使っていた場合は、参考として保持しておきましょう。同じ順序をApidogのドキュメントサイト設定で一度設定します。

ステップバイステップの移行

1. descriptionフィールドの中身を監査する

何かを移動する前に、スペックの中にどれだけのコンテンツがあるかを確認します。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

見出しのリストが、将来のdocs/ファイルのリストになります。私たちのテストでは、info.descriptionは2つのMarkdownファイルに分割され、タグのdescriptionはフォルダごとのイントロページと、追加のMarkdownファイル1つになりました。

2. info.descriptionをMarkdownファイルに分割する

各トップレベルセクションをdocs/配下の独自のファイルにコピーします。見出し、コードサンプル、リンクはそのまま保持します。次に、スペック内のinfo.descriptionを1段落の要約に縮小し、コンテンツが1箇所にのみ存在するようにします。

コピーする際には、Redoc特有の2つの機能に注意してください:

• <SecurityDefinitions />や同様のRedocタグは、Redoc以外ではレンダリングされません。それらを、リファレンス内のセキュリティスキームにリンクする短い文章セクションに置き換えましょう。
• #tag/PaymentsのようなリンクはRedocのアンカーを指しています。最初の公開後に、対応するApidogのドキュメントURLまたはフォルダURLに更新してください。

3. Spec-firstモードでリポジトリを接続する

Spec-firstモードでプロジェクトを作成し、リポジトリ(GitHub、GitLab、Azure DevOps、またはBitbucket)を接続し、openapi.yamlとdocs/フォルダを指定し、Webhookをインストールします。それ以降は、追跡ブランチへのプッシュがプロジェクトを更新します。

最初の同期後、Specsワークスペースにスペックとリポジトリの残りの内容が表示されます。APIsタブにはopenapi.yamlから解析されたオペレーションが一覧表示され、DocsにはMarkdownページが保持され、All filesはリポジトリをミラーリングします。

Webhookがこれをdocs-as-codeワークフローとして維持する鍵です。これがないと、手動で同期をトリガーしなければなりません。これがなぜ重要なのかについては、docs as codeのガイドをご覧ください。

4. ドキュメントサイトを公開し、ナビゲーションを設定する

プロジェクトからドキュメントサイトを公開し、サイドバーを整えます。ほとんどのRedoclyユーザーが望み、私たちが再現した順序は次のとおりです:

1. Getting Started
2. Authentication
3. Integration guides
4. API Reference(タグからのエンドポイントフォルダ)

MarkdownページとAPIフォルダは1つのツリー内で自由に混在できるため、現在のRedoclyのサイドバーに近い形で再現できます。

5. カスタムドメインを追加する

developers.example.comのようなCNAMEをドキュメントサイトに向けます。カスタムドメインはFreeプランでも利用できます。

コーディングエージェントにApidog CLIでタグのdescriptionを移行させる

タグのdescriptionが最も退屈な作業です。13個のタグは13回のコピー&ペースト作業を意味し、移行中にタグのdescriptionが変更されるたびにやり直すことになります。代わりにコーディングエージェントに任せましょう。

Apidog CLIは、Claude Code、Codex、Cursor、または任意のターミナルエージェントに、エンドポイントフォルダを含むプロジェクトへの構造化JSONアクセスを提供します。一度セットアップします:

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

最後の行はApidogスキルをインストールし、エージェントが推測せずにコマンドを把握できるようにします。インストールガイドではトークンとプライベートデプロイについて説明しています。

次に、エージェントに1つのプロンプトを与えます:

openapi.yamlを読んでください。descriptionを持つすべてのタグについて、Apidogプロジェクト<PROJECT_ID>内の一致するエンドポイントフォルダを見つけ、そのフォルダのdescriptionをタグのdescriptionに設定してください。書き込む前に、各ペイロードをapidog cli-schema validate folder-updateで検証してください。変更したフォルダのリストを見せてください。

エージェントが実行する内容は次のとおりです:

# 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

folder-updateスキーマはname、parentId、descriptionを受け付けます。descriptionはエンドポイントフォルダとテストシナリオフォルダでサポートされています。単一のタグに属さないガイドについては、エージェントはapidog doc listとapidog doc createを同じように使用できます。その前にapidog cli-schema get doc-createを読む必要があります。

公開サイトでフォルダのイントロを表示するには、フォルダの設定内のDocumentation Settings after PublicationにあるFolder Contents Displaying Settingを設定します。

正直な注意点を1つ挙げると、タグのdescriptionをカテゴリごとのイントロページとして表示する機能は動作しますが、あまり文書化されていない経路に依存しています。すべてのフォルダで依存する前に、自分のワークスペースで2、3個のフォルダでテストしてください。エージェント駆動のスペック作業の詳細については、Claude CodeでのApidog CLIの使用やエージェントにAPIスペックを更新させるをご覧ください。

Gitの外に残るもの

Spec-firstプロジェクトは、APIとMarkdownをGitに保持します。一部のポータル設定はApidogインターフェース内にあり、バージョン管理されません:

これらは一度設定すればよい項目です。新しいトップレベルセクションを追加するときに触るものであり、コンテンツ変更のたびに触るものではありません。Redoclyはこのうちより多くのものをredocly.yamlとsidebars.yamlに保持しているため、今日プルリクエストでナビゲーション変更をレビューしているなら、それがUIに移ることを想定しておいてください。

プランと料金

ここで説明したセットアップはFreeプランに収まり、カスタムドメインも含まれます。Freeは最大4人のチームメンバーまで対応します。有料プランでは、プロジェクトごとに複数のドキュメントサイトやカスタム可視性コントロールなどが追加されます。現在の制限についてはApidogの料金をご確認ください。

移行後のRedocly vs. Apidog

トレードオフはシンプルです。YAMLで定義されたナビゲーションを失います。代わりに、ドキュメントの元となる同じスペック上で、テスト、モック、エージェントフレンドリーなCLIを得ます。CLIごとの比較については、Apidog CLI vs Redocly CLIをお読みください。

FAQ

RedoclyでホストされていたURLは引き続き機能しますか? 自動的には機能しません。ページパスが変わります。以前のポータルにトラフィックの多いガイドURLがあった場合、ドメインを切り替えた後に主要ページ用のリダイレクトをDNSまたはプロキシ層で追加してください。

OpenAPIスペックを書き直す必要がありますか? いいえ。スペックはそのままインポートされます。ナラティブコンテンツをinfo.descriptionとtags[].descriptionからMarkdownファイルに移動するだけです。

x-tagGroupsを保持できますか? 代わりにグループ化にはフォルダを使用してください。各タグはフォルダになり、フォルダをネストしてタググループを再現できます。

Stoplightからの移行と比べてどうですか? 形は似ています。Git内のスペック、隣接するMarkdown、Webhook同期です。両方のツールを使っている場合はStoplightからApidogへの移行方法をご覧ください。

自分のワークスペースで手順の動作が異なる場合は? 私たちの結果はテスト環境から得たものです。まずブランチでインポートを再実行し、DNSを切り替える前に公開ポータルと現在のポータルを比較してください。

午後には移行を完了しましょう

RedoclyからApidogへの移行は、ほとんどがコンテンツの移動です。スペックはそのままインポートされます。ガイドはdescriptionフィールドからdocs/フォルダに一度移動します。その後はWebhookがすべてを同期し続けます。反復的なタグのdescription作業はApidog CLIでエージェントに任せ、自分の時間は公開ポータルをページごとに確認するために使いましょう。

Apidogをダウンロードして、リポジトリをSpec-firstモードに接続し、移行を開始してください。