Wie Sie von Redocly zu Apidog migrieren, ohne Ihren Docs-as-Code-Workflow zu verlieren

Wenn Sie Ihr Entwicklerportal auf Redocly betreiben, arbeiten Sie bereits so, wie es sich die meisten API-Teams wünschen: openapi.yaml liegt in Git, Guides sind Markdown, und ein Push aktualisiert die Doku. Die Angst beim Toolwechsel ist, genau diese Schleife zu verlieren und am Ende die Doku von Hand in einer Web-Oberfläche zu bearbeiten.

Das muss nicht sein. Der Apidog-Spec-first-Modus hält Ihre Spezifikation und Ihr Markdown im selben Repository, synchronisiert bei jedem Push über einen Webhook und veröffentlicht ein Portal mit Guides und einer API-Referenz in einer einzigen Seitenleiste. Dieser Leitfaden führt durch die Migration – einschließlich des einen Teils, der nicht automatisch übernommen wird: die langen Inhalte, die viele Redocly-Nutzer in info.description und tags[].description pflegen.

Wenn Sie noch Tools vergleichen, beginnen Sie mit Apidog vs. Redocly oder der breiteren Liste der Redocly-Alternativen. Dieser Beitrag setzt voraus, dass Sie sich für Apidog entschieden haben und umziehen möchten, ohne Ihren Workflow zu zerstören.

Was übernommen wird und was nicht

Wir haben diese Migration mit einer echten Produktionsspezifikation getestet: OpenAPI 3.0.3, 62 Operationen über 13 Tags hinweg, mit Getting-started-, Authentifizierungs- und Integrationsinhalten, die in die Beschreibungsfelder der Spezifikation geschrieben waren. Hier ist, was beim Import passiert ist.

Die API-Referenz wird ohne Änderungen übernommen. Die Lücke ist der erzählende Inhalt.

Warum Ihre Beschreibungsfelder nicht gleich gerendert werden

Redoc, der Renderer hinter den Referenz-Dokumentationen von Redocly, behandelt info.description als Mini-Dokument. Jede Markdown-Überschrift darin wird zu einem Eintrag in der Seitenleiste, weshalb Teams dort oft ihre gesamten „Getting started“- und „Authentication“-Guides schreiben. Tag-Beschreibungen werden als Einführungstext oben in jeder Tag-Gruppe gerendert.

Das ist eine Redoc-Konvention, nicht Teil der OpenAPI Specification. Die Spezifikation definiert description lediglich als CommonMark-String. Apidog hält Guides – wie die meisten Portale – als eigenständige Markdown-Dokumente und behält die Spezifikation für die Referenz. Eine Standard-Veröffentlichung nach dem Import zeigt nur die API-Referenz, ohne die Guides, die Sie in den Beschreibungsfeldern geschrieben haben.

Die Lösung ist ein einmaliger Umzug: Heben Sie diesen Inhalt aus dem YAML in Markdown-Dateien daneben. Danach bleibt alles Git-gesteuert.

Das Ziel-Repository-Layout

Dies ist die Struktur, die wir validiert haben:

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

openapi.yaml steuert die API-Referenz. Jede Datei in docs/ wird zu einer Seite in der Portal-Seitenleiste. Bilder, auf die diese Markdown-Dateien verweisen, können im selben Repository liegen und werden mit ihnen synchronisiert.

Wenn Sie die sidebars.yaml von Redocly verwendet haben, um Ihre Navigation zu ordnen, behalten Sie sie als Referenz. Sie legen dieselbe Reihenfolge einmal in den Doku-Website-Einstellungen von Apidog fest.

Schritt-für-Schritt-Migration

1. Prüfen Sie, was in Ihren Beschreibungsfeldern steckt

Bevor Sie etwas verschieben, sehen Sie nach, wie viel Inhalt in der Spezifikation steckt. Mit 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

Die Überschriftenliste ist Ihre künftige docs/-Dateiliste. In unserem Test ließ sich info.description in zwei Markdown-Dateien aufteilen, und die Tag-Beschreibungen wurden zu Einführungsseiten pro Ordner plus einer zusätzlichen Markdown-Datei.

2. Teilen Sie info.description in Markdown-Dateien auf

Kopieren Sie jeden Abschnitt der obersten Ebene in eine eigene Datei unter docs/. Behalten Sie die Überschriften, Codebeispiele und Links bei. Kürzen Sie dann info.description in der Spezifikation auf eine Zusammenfassung von einem Absatz, damit der Inhalt nur an einer Stelle liegt.

Achten Sie beim Kopieren auf zwei Redoc-spezifische Funktionen:

• <SecurityDefinitions /> und ähnliche Redoc-Tags werden außerhalb von Redoc nicht gerendert. Ersetzen Sie sie durch einen kurzen geschriebenen Abschnitt, der auf die Security-Schemes in der Referenz verlinkt.
• Links wie #tag/Payments verweisen auf Redoc-Anker. Aktualisieren Sie sie nach der ersten Veröffentlichung auf die passenden Apidog-Doku- oder Ordner-URLs.

3. Verbinden Sie das Repository im Spec-first-Modus

Erstellen Sie ein Projekt im Spec-first-Modus, verbinden Sie Ihr Repository (GitHub, GitLab, Azure DevOps oder Bitbucket), richten Sie es auf openapi.yaml und den Ordner docs/ aus und installieren Sie den Webhook. Von da an aktualisiert ein Push in den überwachten Branch das Projekt.

Nach der ersten Synchronisierung zeigt der Arbeitsbereich Specs Ihre Spezifikation und den Rest des Repositorys. Der Tab APIs listet die aus openapi.yaml geparsten Operationen auf, Docs enthält Ihre Markdown-Seiten, und Alle Dateien spiegelt das Repository wider.

Der Webhook ist es, was dies zu einem Docs-as-Code-Workflow macht. Ohne ihn müssten Sie Synchronisierungen von Hand auslösen. Eine Auffrischung, warum das wichtig ist, finden Sie in unserem Leitfaden zu Docs as Code.

4. Veröffentlichen Sie die Doku-Website und legen Sie die Navigation fest

Veröffentlichen Sie eine Doku-Website aus dem Projekt und ordnen Sie die Seitenleiste an. Die Reihenfolge, die sich die meisten Redocly-Nutzer wünschen – und die wir reproduziert haben – ist:

1. Getting Started
2. Authentication
3. Integrationsleitfäden
4. API-Referenz (die Endpoint-Ordner aus Ihren Tags)

Markdown-Seiten und API-Ordner lassen sich in einem Baum frei mischen, sodass Sie Ihre aktuelle Redocly-Seitenleiste nah abbilden können.

5. Fügen Sie Ihre eigene Domain hinzu

Richten Sie einen CNAME wie developers.example.com auf die Doku-Website. Eigene Domains sind im Free-Plan verfügbar.

Lassen Sie Ihren Coding-Agenten Tag-Beschreibungen mit Apidog CLI migrieren

Tag-Beschreibungen sind der mühsamste Teil. Dreizehn Tags bedeuten dreizehn Copy-Paste-Vorgänge, und Sie werden sie jedes Mal wiederholen, wenn sich während der Übergangsphase eine Tag-Beschreibung ändert. Übergeben Sie das stattdessen Ihrem Coding-Agenten.

Apidog CLI gibt Claude Code, Codex, Cursor oder jedem Terminal-Agenten strukturierten JSON-Zugriff auf Ihr Projekt, einschließlich der Endpoint-Ordner. Richten Sie es einmal ein:

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

Die letzte Zeile installiert den Apidog-Skill, damit Ihr Agent die Befehle kennt, ohne raten zu müssen. Der Installationsleitfaden behandelt Tokens und private Deployments.

Geben Sie Ihrem Agenten dann einen Prompt:

Lesen Sie openapi.yaml. Suchen Sie für jeden Tag mit einer Beschreibung den passenden Endpoint-Ordner im Apidog-Projekt <PROJECT_ID> und setzen Sie die Beschreibung dieses Ordners auf die Beschreibung des Tags. Validieren Sie jede Payload mit apidog cli-schema validate folder-update, bevor Sie schreiben. Zeigen Sie mir die Liste der Ordner, die Sie geändert haben.

Hier ist, was der Agent ausführt:

# 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

Das folder-update-Schema akzeptiert name, parentId und description, und description wird für Endpoint- und Test-Szenario-Ordner unterstützt. Für Guides, die nicht zu einem einzelnen Tag gehören, kann der Agent auf dieselbe Weise apidog doc list und apidog doc create verwenden, nachdem er apidog cli-schema get doc-create gelesen hat.

Um die Einführung eines Ordners auf der veröffentlichten Website anzuzeigen, legen Sie Folder Contents Displaying Setting in den Einstellungen des Ordners unter Documentation Settings after Publication fest.

Eine ehrliche Einschränkung: Das Sichtbarmachen von Tag-Beschreibungen als Einführungsseiten pro Kategorie funktioniert, stützt sich aber auf einen weniger dokumentierten Pfad. Testen Sie es mit zwei oder drei Ordnern in Ihrem eigenen Arbeitsbereich, bevor Sie sich für alle darauf verlassen. Weitere agentengesteuerte Arbeiten an der Spezifikation finden Sie unter Verwendung von Apidog CLI in Claude Code und einen Agenten Ihre API-Spezifikation aktualisieren lassen.

Was außerhalb von Git bleibt

Ein Spec-first-Projekt hält Ihre API und Ihr Markdown in Git. Einige Portal-Einstellungen leben in der Apidog-Oberfläche und sind nicht versioniert:

Dies sind einmalig festzulegende Punkte. Sie fassen sie an, wenn Sie einen neuen Abschnitt der obersten Ebene hinzufügen, nicht bei jeder Inhaltsänderung. Redocly hält mehr davon in redocly.yaml und sidebars.yaml. Wenn Sie Navigationsänderungen heute also in Pull Requests prüfen, planen Sie ein, dass dies in die UI wandert.

Plan und Preisgestaltung

Das hier beschriebene Setup passt in den Free-Plan, eigene Domain inklusive. Free deckt bis zu 4 Teammitglieder ab. Kostenpflichtige Pläne fügen Dinge wie mehrere Dokumentations-Websites pro Projekt und eigene Sichtbarkeitssteuerungen hinzu. Prüfen Sie die Apidog-Preisgestaltung für die aktuellen Limits.

Redocly vs. Apidog nach der Migration

Der Tausch ist einfach. Sie verlieren die YAML-definierte Navigation. Sie gewinnen Testing, Mocking und eine agentenfreundliche CLI auf derselben Spezifikation, aus der Ihre Doku stammt. Eine detaillierte Gegenüberstellung CLI für CLI finden Sie unter Apidog CLI vs. Redocly CLI.

FAQ

Funktionieren meine von Redocly gehosteten URLs weiterhin? Nicht automatisch. Seitenpfade ändern sich. Wenn Ihr altes Portal stark frequentierte Guide-URLs hatte, fügen Sie nach dem Domainwechsel Weiterleitungen auf DNS- oder Proxy-Ebene für die Hauptseiten hinzu.

Muss ich meine OpenAPI-Spezifikation neu schreiben? Nein. Die Spezifikation wird unverändert importiert. Sie verschieben lediglich erzählenden Inhalt aus info.description und tags[].description in Markdown-Dateien.

Kann ich x-tagGroups behalten? Verwenden Sie stattdessen Ordner zur Gruppierung. Jeder Tag wird zu einem Ordner, und Sie können Ordner verschachteln, um Ihre Tag-Gruppen abzubilden.

Wie schneidet das im Vergleich zur Migration von Stoplight ab? Die Form ist ähnlich: Spezifikation in Git, Markdown daneben, Webhook-Synchronisierung. Siehe wie Sie von Stoplight zu Apidog migrieren, wenn Sie beide Tools betreiben.

Was, wenn sich ein Schritt in meinem Arbeitsbereich anders verhält? Unsere Ergebnisse stammen aus einer Testumgebung. Führen Sie den Import zuerst in einem Branch erneut aus und vergleichen Sie das veröffentlichte Portal mit Ihrem aktuellen, bevor Sie das DNS umstellen.

Schaffen Sie den Umzug an einem Nachmittag

Eine Migration von Redocly zu Apidog ist größtenteils ein Inhaltsumzug. Ihre Spezifikation wird unverändert importiert. Ihre Guides ziehen einmalig aus den Beschreibungsfeldern in einen Ordner docs/ um. Ein Webhook hält danach alles synchron. Lassen Sie Ihren Agenten die repetitive Arbeit an den Tag-Beschreibungen mit Apidog CLI erledigen, und verbringen Sie Ihre eigene Zeit damit, das veröffentlichte Portal Seite für Seite zu prüfen.

Laden Sie Apidog herunter und verbinden Sie Ihr Repository mit dem Spec-first-Modus, um die Migration zu starten.