DEV Community

Cover image for Stoplight zu Apidog migrieren: Spec-First-Workflow Anleitung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Stoplight zu Apidog migrieren: Spec-First-Workflow Anleitung

Wenn Sie von Stoplight Studio oder Stoplight Platform zu Apidog wechseln, müssen Sie Ihre OpenAPI-Spezifikationen nicht neu erstellen oder erneut hochladen. Der Spec-First-Modus von Apidog verbindet sich direkt mit Ihrem bestehenden GitHub- oder GitLab-Repository. Git bleibt damit die einzige Quelle der Wahrheit, inklusive Commit-Historie, Branches und Pull-Request-Workflow. In diesem Leitfaden migrieren Sie Schritt für Schritt: Stoplight-Assets sichern, Verzeichnisstruktur prüfen, .stoplight.json und toc.json ersetzen und Apidog mit Ihrem Repository verbinden.

Teste Apidog noch heute

Teams wie das World Economic Forum verwalten OpenAPI-Spezifikationen bereits in Git und nutzen Stoplight für Dokumentation. Wenn Ihr Setup ähnlich aussieht, können Sie die Migration als Konfigurationswechsel behandeln, nicht als vollständige Datenmigration. Wenn Sie noch Alternativen evaluieren, hilft zusätzlich der Überblick zu den besten Stoplight Studio-Alternativen.

Was sich bei der Migration nicht ändert

Ihre OpenAPI-Dateien, Ihr Git-Repository und Ihre Branch-Strategie bleiben unverändert. Stoplight speichert Spezifikationen als YAML- oder JSON-Dateien in der Versionskontrolle. Apidog liest dieselben Dateien im Spec-First-Modus.

Was sich ändert, ist die Tool-Schicht darüber:

  • Dokumentations-Renderer
  • Mock-Server
  • Test-Runner
  • API-Client
  • Workspace-Konfiguration

Statt Stoplight für Dokumentation und ein separates Tool wie Postman für Tests zu verwenden, bündelt Apidog diese Workflows in einem Workspace, der mit derselben OpenAPI-Datei synchronisiert wird.

Das praktische Ergebnis: Sie migrieren primär Konfiguration, nicht Spezifikationsdaten.

Schritt 1: Stoplight-Projekt-Assets sichern

Bevor Sie Apidog verbinden, stellen Sie sicher, dass alle relevanten Dateien lokal oder in Git verfügbar sind.

Wenn Sie Stoplight Studio mit Git-Backend verwenden

Ihre OpenAPI-Spezifikationen, JSON-Schema-Modelle und Markdown-Dokumentation sind normalerweise bereits committed. Aktualisieren Sie zuerst Ihren lokalen Stand:

git checkout main
git pull
Enter fullscreen mode Exit fullscreen mode

Stoplight nutzt das OpenAPI-Spezifikationsformat. Diese Spezifikationsdateien funktionieren in Apidog ohne Konvertierung.

Eine typische Stoplight-Struktur sieht so aus:

your-api-repo/
  .stoplight.json          # Stoplight-Projektkonfiguration
  reference/
    petstore.yaml          # OpenAPI-Spezifikation(en)
  models/
    error.json             # Geteilte JSON-Schema-Modelle
  docs/
    introduction.md        # Markdown-Anleitungsseiten
    authentication.md
  toc.json                 # Stoplight-Inhaltsverzeichnis
  assets/
    images/
      architecture.png
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie zusätzlich, ob alle Änderungen committed sind:

git status
Enter fullscreen mode Exit fullscreen mode

Wenn noch unversionierte Dateien existieren, committen Sie diese vor der Migration.

Wenn Sie Stoplight Platform ohne Git-Backend verwenden

Exportieren Sie die Dateien manuell aus der Stoplight-Oberfläche:

  1. Öffnen Sie jedes API-Projekt in Stoplight.
  2. Gehen Sie zu Exportieren.
  3. Laden Sie die OpenAPI YAML herunter.
  4. Kopieren Sie Markdown-Dokumente in einen neuen docs/-Ordner.
  5. Legen Sie ein neues GitHub- oder GitLab-Repository an.
  6. Committen Sie Spezifikation, Dokumentation und Assets.

Beispiel:

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

mkdir reference docs assets
cp ~/Downloads/openapi.yaml reference/api.yaml

git init
git add .
git commit -m "Import Stoplight API specification and docs"
Enter fullscreen mode Exit fullscreen mode

Sobald die Dateien in Git liegen, können Sie Apidog verbinden.

Schritt 2: Stoplight-Konfigurationsdateien zuordnen

Stoplight verwendet vor allem zwei proprietäre Dateien für die Projektstruktur:

Stoplight-Datei Funktion Apidog-Äquivalent
.stoplight.json Definiert Projekt-Root, Spezifikationspfade, Dokumentationspfade und enthaltene Dateien Repository-Verbindungseinstellungen im Apidog-Projekt
toc.json Steuert Reihenfolge und Gruppierung der Dokumentationsseitenleiste Seitenstruktur im Apidog-Dokumentationseditor
reference/ Typischer Speicherort für OpenAPI-Dateien Im Apidog Spec-First-Modus konfigurierbarer Spezifikationspfad
models/ Speicherort für geteilte JSON-Schema-Dateien Referenzen über components/schemas und $ref
docs/ Markdown-Anleitungsseiten Import als Dokumentationsseiten in Apidog

Wichtig: .stoplight.json und toc.json haben keine direkte Funktion in Apidog. Sie können die Dateien zunächst im Repository lassen. Apidog ignoriert unbekannte Dateien.

Eine typische Stoplight-Konfiguration könnte so aussehen:

{
  "name": "your-api",
  "version": "1.0",
  "files": {
    "api": "reference/api.yaml",
    "docs": "docs"
  }
}
Enter fullscreen mode Exit fullscreen mode

In Apidog konfigurieren Sie diese Informationen nicht über eine JSON-Datei, sondern über die Projektoberfläche:

  • Repository auswählen
  • Branch auswählen
  • OpenAPI-Datei oder Spezifikationspfad auswählen
  • Dokumentationsseiten importieren
  • Seitenleistenstruktur im Editor festlegen

Schritt 3: Repository mit dem Apidog Spec-First-Modus verbinden

Der Apidog Spec-First-Modus verbindet Ihr GitHub- oder GitLab-Repository mit einem Apidog-Projekt. Die OpenAPI-Spezifikation wird aus Git gelesen, nicht aus einer isolierten Apidog-Datenbank.

So bleibt Ihr bestehender Workflow erhalten:

  • Entwickler ändern OpenAPI-Dateien lokal.
  • Änderungen laufen über Pull Requests.
  • Git bleibt die Quelle der Wahrheit.
  • Apidog synchronisiert die Spezifikation aus dem Repository.

Wenn Sie die OAuth-Freigabe prüfen möchten, lesen Sie zusätzlich die GitHub-Dokumentation zum Autorisieren von GitHub Apps.

Verbindung einrichten

  1. Erstellen Sie in Apidog ein neues Projekt im Spec-First-Modus.
  2. Authentifizieren Sie Apidog mit GitHub oder GitLab.
  3. Wählen Sie das Repository aus.

  1. Wählen Sie den Branch:
    • main oder master für Produktionsspezifikationen
    • Feature-Branch für Migrationstests

  1. Wählen Sie die OpenAPI-Datei, z. B.: 
reference/api.yaml
Enter fullscreen mode Exit fullscreen mode
  1. Speichern Sie die Verbindung.

Apidog liest anschließend die Spezifikation und erstellt daraus:

  • interaktive API-Dokumentation
  • Mock-Endpunkte
  • Testgrundlage
  • API-Client-Struktur

Wenn Ihre Spezifikation externe $ref-Pfade nutzt, löst Apidog diese relativ zum Speicherort der OpenAPI-Datei auf.

Beispiel:

components:
  schemas:
    Error:
      $ref: "../models/error.json"
Enter fullscreen mode Exit fullscreen mode

Wenn reference/api.yaml auf ../models/error.json verweist, muss die Struktur im Repository entsprechend vorhanden sein:

your-api-repo/
  reference/
    api.yaml
  models/
    error.json
Enter fullscreen mode Exit fullscreen mode

Weitere Details zur Git-Synchronisierung finden Sie im Leitfaden zur Synchronisierung von OpenAPI-Spezifikationen mit GitHub.

Schritt 4: Markdown-Dokumentation migrieren

Stoplight erlaubt Markdown-Anleitungsseiten neben API-Referenzen. Apidog unterstützt denselben Dokumentationstyp über den Dokumentationseditor.

Nach der Repository-Verbindung importieren Sie Ihre Dateien aus docs/.

Markdown-Dateien importieren

  1. Öffnen Sie Ihr Apidog-Projekt.
  2. Wechseln Sie zu Dokumente.
  3. Wählen Sie Importieren > Markdown.
  4. Laden Sie Ihre Markdown-Dateien hoch oder fügen Sie Inhalte seitenweise ein.
  5. Ordnen Sie die Seiten in der gewünschten Reihenfolge an.

Bildpfade prüfen

Wenn Ihre Markdown-Dateien lokale Bilder referenzieren, z. B.:

![Architektur](../assets/images/architecture.png)
Enter fullscreen mode Exit fullscreen mode

prüfen Sie nach dem Import, ob die Bilder korrekt geladen werden.

Für lokale Assets haben Sie zwei Optionen:

  1. Bilder in den Apidog-Dateispeicher hochladen und Markdown-Links aktualisieren.
  2. Bilder auf einem CDN oder öffentlichen Speicher bereitstellen und die URLs ersetzen.

Beispiel mit öffentlicher URL:

![Architektur](https://cdn.example.com/api-docs/architecture.png)
Enter fullscreen mode Exit fullscreen mode

Wenn Ihre Bilder bereits öffentlich gehostet sind, müssen Sie nichts ändern.

Schritt 5: Stoplight-Mock-Server ersetzen

Stoplight Studio bietet einen lokalen Mock-Server, der OpenAPI-Spezifikationen liest und Beispielantworten zurückgibt.

Typischer Stoplight-Befehl:

stoplight mock reference/api.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog generiert Mock-Endpunkte aus der verbundenen OpenAPI-Spezifikation. Der Unterschied: Der Mock-Server ist cloudbasiert und für das Team über eine gemeinsame URL erreichbar.

Was Sie prüfen sollten

Nach der Synchronisierung:

  1. Öffnen Sie die API in Apidog.
  2. Wählen Sie einen Endpunkt aus.
  3. Prüfen Sie die generierte Mock-URL.
  4. Senden Sie eine Testanfrage.
  5. Vergleichen Sie Statuscode, Header und Response Body mit Ihren bisherigen Stoplight-Mocks.

Beispielhafte OpenAPI-Response:

paths:
  /orders:
    post:
      responses:
        "201":
          description: Order created
          headers:
            location:
              schema:
                type: string
          content:
            application/json:
              examples:
                created:
                  value:
                    id: "ord_123"
                    status: "created"
Enter fullscreen mode Exit fullscreen mode

Apidog verwendet definierte examples, wenn diese in der Spezifikation vorhanden sind. Wenn keine Beispiele definiert sind, kann die Mock-Engine Beispielwerte erzeugen. Antwortregeln können pro Endpunkt in Apidog überschrieben werden, ohne die OpenAPI-Datei zu ändern.

Für Teams, die bisher lokale Mocks nutzen, ist der wichtigste Migrationstest:

  • Können Frontend- und QA-Teams die Cloud-Mock-URL erreichen?
  • Sind Netzwerk- und Sicherheitsrichtlinien erfüllt?
  • Stimmen Mock-Responses mit den erwarteten Testdaten überein?

Schritt 6: Test-Suites neu erstellen

Wenn Sie Stoplight-Vertragstests oder Spectral-Regeln verwenden, migrieren Sie diese getrennt.

Spectral-Lint-Regeln weiterverwenden

Stoplight nutzt Spectral für OpenAPI-Linting. Die Konfiguration liegt üblicherweise in:

.spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog führt Spectral nicht direkt aus. Wenn Ihr Team eigene Spectral-Regeln verwendet, lassen Sie diese weiterhin in CI laufen.

Beispiel für GitHub Actions:

# .github/workflows/openapi-lint.yml
name: OpenAPI Lint

on:
  pull_request:
    branches: [main]

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

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

      - name: OpenAPI-Spezifikation linten
        run: spectral lint reference/api.yaml
Enter fullscreen mode Exit fullscreen mode

So bleibt Ihre bestehende Lint-Policy erhalten, während Apidog Dokumentation, Mocking und Tests übernimmt.

API-Tests in Apidog neu erstellen

Stoplight-Testprojekte lassen sich nicht automatisch in Apidog importieren. Erstellen Sie die relevanten Szenarien im Apidog-Test-Runner neu.

Ein typisches Testszenario:

  1. POST /orders ausführen
  2. Prüfen, ob der Statuscode 201 ist
  3. Prüfen, ob der Header location vorhanden ist
  4. Optional: Response Body validieren

Wenn Sie Tests in CI ausführen möchten, können Sie die Apidog CLI in GitHub Actions einbinden. Der Leitfaden zum Git-nativen API-Workflow zeigt diesen Ansatz im Detail.

Beispiel:

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

on:
  pull_request:
    branches: [main]

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

      - name: Apidog-Tests ausführen
        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: Testergebnisse veröffentlichen
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml
Enter fullscreen mode Exit fullscreen mode

Damit ersetzen Sie einen Stoplight-Testlauf in CI, ohne Ihre GitHub-Actions-Struktur grundsätzlich zu ändern.

Evaluierungs-Checkliste für Enterprise-Teams

Wenn Sie ein größeres Team oder eine Stoplight-Platform-Umgebung migrieren, testen Sie die folgenden Punkte mit einem repräsentativen Projekt.

Funktion Was Sie in Apidog prüfen sollten
Privater Dokumentationszugriff Können Dokumentationsseiten auf authentifizierte Benutzer oder bestimmte E-Mail-Domänen beschränkt werden?
Schema-/Komponentenwiederverwendung über Projekte hinweg Können gemeinsame components/schemas aus mehreren Projekten referenziert werden, ohne Copy-Paste?
Benutzerdefinierte Lint-Regeln Können gemeinsame Lint-Anforderungen projektübergreifend abgebildet werden? Falls Spectral benötigt wird, bleibt CI der richtige Ort dafür.
SSO-/SCIM-Bereitstellung Unterstützt die SSO-Konfiguration Ihren Identitätsanbieter und passt SCIM zu Ihrem Benutzer-Lifecycle?
Audit-Protokolle Welche Ereignisse werden protokolliert und entspricht das Format Ihren Compliance-Anforderungen?
Netzwerkzugriff auf Mocks Können QA, Frontend und externe Integrationen die Mock-URLs erreichen?
Dokumentations-URLs Können bestehende externe Links per DNS, CDN oder Redirect auf die neue Dokumentation zeigen?

Behandeln Sie diese Punkte als Testplan. In der Regel reicht ein repräsentatives API-Projekt, um die wichtigsten Migrationsrisiken früh zu erkennen.

FAQ

Kann ich Spectral weiterhin mit Apidog verwenden?

Ja. Führen Sie Spectral unabhängig von Apidog in Ihrer CI-Pipeline aus. Ihre .spectral.yaml bleibt im Repository, und GitHub Actions oder GitLab CI linten die OpenAPI-Datei bei jeder PR.

Apidog übernimmt Dokumentation, Mocking und API-Tests. Spectral bleibt für benutzerdefiniertes Linting zuständig. Beide Workflows können parallel laufen. Weitere Optionen finden Sie in der Spectral-Dokumentation.

Werden meine $ref-Pfade unterbrochen, wenn ich das Repository mit Apidog verbinde?

Nicht, wenn die Pfade in Ihrer Spezifikation korrekt sind. Apidog löst $ref relativ zum Speicherort der Stamm-OpenAPI-Datei auf.

Beispiel:

components:
  schemas:
    Error:
      $ref: "../models/error.json"
Enter fullscreen mode Exit fullscreen mode

Wenn api.yaml in reference/ liegt und models/ eine Ebene darüber, funktioniert der relative Pfad:

your-api-repo/
  reference/
    api.yaml
  models/
    error.json
Enter fullscreen mode Exit fullscreen mode

Testen Sie die Migration zuerst mit einer Spezifikation, die externe Referenzen enthält.

Unterstützt der Apidog Spec-First-Modus sowohl GitLab als auch GitHub?

Ja. GitHub und GitLab werden unterstützt. Der Ablauf ist ähnlich:

  1. Konto authentifizieren
  2. Repository auswählen
  3. Branch auswählen
  4. OpenAPI-Datei konfigurieren

Weitere Hinweise zu Branch-Strategien finden Sie im Leitfaden zur OpenAPI-Versionskontrolle mit Git.

Was passiert mit meiner bestehenden Stoplight-Dokumentations-URL?

Von Stoplight gehostete URLs wie:

docs.stoplight.io/your-org/your-api
Enter fullscreen mode Exit fullscreen mode

funktionieren nicht mehr, sobald Sie Ihr Stoplight-Abonnement kündigen oder die Dokumentation dort entfernen.

Planen Sie deshalb vor der Umstellung:

  • neue Apidog-Dokumentations-URL konfigurieren
  • externe Links identifizieren
  • Weiterleitungen auf DNS-, CDN- oder Reverse-Proxy-Ebene einrichten
  • interne Dokumentationslinks aktualisieren

Muss ich .stoplight.json und toc.json löschen?

Nein. Apidog ignoriert unbekannte Dateien. Lassen Sie .stoplight.json und toc.json zunächst im Repository, wenn das Entfernen Merge-Konflikte oder Verwirrung verursachen würde.

Nach der vollständigen Umstellung können Sie die Dateien in einem Cleanup-PR entfernen:

git rm .stoplight.json toc.json
git commit -m "Remove Stoplight configuration files"
Enter fullscreen mode Exit fullscreen mode

Für die Migration selbst ist das Löschen nicht erforderlich.

Fazit

Die Migration von Stoplight zu Apidog ist kein Neuaufbau Ihrer API-Spezifikation. Ihre OpenAPI-Dateien bleiben in Git, Ihr Branch-Workflow bleibt erhalten, und Verzeichnisse wie reference/, models/ und docs/ lassen sich weiterhin nutzen.

Der konkrete Ablauf:

  1. Stoplight-Dateien und Dokumentation sichern.
  2. Repository-Struktur prüfen.
  3. .stoplight.json und toc.json nicht mehr als aktive Konfiguration verwenden.
  4. Repository im Apidog Spec-First-Modus verbinden.
  5. Markdown-Dokumentation importieren.
  6. Mock-Endpunkte testen.
  7. API-Tests in Apidog neu erstellen.
  8. Spectral bei Bedarf weiter in CI ausführen.

Starten Sie die Migration, indem Sie den Apidog Spec-First-Modus mit Ihrem bestehenden GitHub- oder GitLab-Repository verbinden. Verwenden Sie dafür zuerst ein repräsentatives API-Projekt und arbeiten Sie die Evaluierungs-Checkliste mit Ihren echten Spezifikationen, Schemas und Dokumentationsseiten durch.

Sie können außerdem Apidog herunterladen, um die Migration lokal vorzubereiten und Ihr Team mit dem neuen Workflow vertraut zu machen.

Top comments (0)