Stoplight zu Apidog migrieren: Spec-First-Workflow Anleitung

Wenn Sie von Stoplight Studio oder Stoplight Platform zu Apidog wechseln, sollten Sie als Erstes wissen, dass Sie Ihre OpenAPI-Spezifikationen nicht erneut hochladen müssen. Der Spec-First-Modus von Apidog (derzeit in der Beta-Phase) verbindet sich direkt mit Ihrem bestehenden GitHub- oder GitLab-Repository, sodass Git die einzige Quelle der Wahrheit bleibt und Ihre Commit-Historie intakt ist. Dieser Leitfaden führt Sie durch jeden Schritt: den Export Ihrer Stoplight-Konfiguration, die Zuordnung ihrer Verzeichnis-Konventionen zu den Erwartungen von Apidog und das Ersetzen von .stoplight.json und toc.json durch ihre Apidog-Äquivalente.

Teams wie die des World Economic Forum verwalten OpenAPI-Spezifikationen bereits in Git zusammen mit Stoplight für die Dokumentation. Wenn dies Ihre Einrichtung beschreibt, ist dieser Leitfaden für Sie geschrieben. Und wenn Sie noch Optionen abwägen, anstatt sich auf eine Migration festzulegen, behandelt der Beitrag über die besten Stoplight Studio-Alternativen die umfassendere Landschaft.

Was sich bei der Migration nicht ändert

Ihre OpenAPI-Dateien, Ihr Git-Repository und Ihre Branch-Strategie ändern sich nicht. Das ist die zentrale Annahme. Stoplight speichert Spezifikationen als YAML- oder JSON-Dateien, die in die Versionskontrolle eingecheckt sind. Apidog liest dieselben Dateien, wenn Sie ein Repository im Spec-First-Modus verbinden.

Was sich ändert, ist alles, was darüber liegt: der Dokumentations-Renderer, der Mock-Server, der Test-Runner und der API-Client. Anstatt dass die Stoplight Platform Dokumente bereitstellt und Postman Tests als separates Tool handhabt, kombiniert Apidog all dies in einem einzigen Arbeitsbereich, synchronisiert mit derselben OpenAPI-Datei, die Ihre Ingenieure bereits committen.

Das praktische Ergebnis: Ihre Migration ist hauptsächlich ein Konfigurationsaustausch, keine Datenmigration.

Schritt 1: Exportieren Sie Ihre Stoplight-Projekt-Assets

Bevor Sie Apidog nutzen, erfassen Sie alles, was Stoplight enthält und noch nicht in Git ist.

Wenn Sie Stoplight Studio mit einem Git-Backend verwenden:

Ihre OpenAPI-Spezifikationen, JSON-Schema-Modelle und Markdown-Dokumentation sind bereits committed. Führen Sie ein git pull aus, um sicherzustellen, dass Ihr lokaler Klon aktuell ist. Stoplight folgt dem OpenAPI-Spezifikationsformat, und diese Spezifikationsdateien funktionieren in Apidog ohne Konvertierung. Ihre Repository-Struktur sieht wahrscheinlich so aus:

your-api-repo/
  .stoplight.json          # Projektkonfiguration (muss ersetzt werden)
  reference/
    petstore.yaml          # Ihre OpenAPI-Spezifikation(en)
  models/
    error.json             # Geteilte JSON-Schema-Modelle
  docs/
    introduction.md        # Markdown-Anleitungsseiten
    authentication.md
  toc.json                 # Reihenfolge des Inhaltsverzeichnisses (muss ersetzt werden)
  assets/
    images/
      architecture.png

Wenn Sie Stoplight Platform (Cloud-basiert, kein Git-Backend) verwenden:

Exportieren Sie Ihre Spezifikationen aus der Stoplight-Benutzeroberfläche: Öffnen Sie jedes API-Projekt, gehen Sie zu „Exportieren“ und laden Sie die OpenAPI YAML herunter. Für Markdown-Dokumente kopieren Sie diese in einen docs/-Ordner in einem neuen Git-Repository. Stoplight bietet keinen Massenexport für Nicht-Git-Projekte an, also müssen Sie dies pro API-Projekt tun.

Sobald Ihre Dateien in einem Git-Repository (GitHub oder GitLab) sind, fahren Sie mit dem nächsten Schritt fort.

Schritt 2: Verstehen Sie die Konfigurationsdateien, die Sie ersetzen

Zwei Stoplight-spezifische Dateien bestimmen die Projektstruktur. Keine davon hat ein direktes Gegenstück in Apidog, aber wenn Sie verstehen, was sie tun, wissen Sie genau, was Sie stattdessen in Apidog konfigurieren müssen.

Die Haupterkenntnis: .stoplight.json und toc.json sind Stoplight-proprietär. Sie können sie im Repository belassen (Apidog ignoriert unbekannte Dateien), aber sie werden in Apidog keine Funktion haben. Die entsprechenden Einstellungen konfigurieren Sie über die Apidog-Projekt-Benutzeroberfläche.

Schritt 3: Verbinden Sie Ihr Repository mit dem Apidog Spec-First-Modus

Der Apidog Spec-First-Modus ist die Methode, wie Sie ein GitHub- oder GitLab-Repository mit einem Apidog-Projekt verknüpfen, sodass die OpenAPI-Spezifikation immer aus Git gelesen wird und nicht aus einer internen Apidog-Datenbank. Dies hält Git als die maßgebliche Quelle, und es bedeutet, dass Ihre Ingenieure weiterhin PRs einreichen können, um die Spezifikation genau wie heute zu aktualisieren.

Hier ist der Verbindungsablauf. Sie können auch die GitHub-Dokumentation zum Verbinden von Drittanbieter-Apps mit Repositories überprüfen, wenn Sie unsicher bezüglich der OAuth-Berechtigungsvergabe sind.

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

3.Legen Sie den Branch fest: Verwenden Sie Ihren Standard-Branch (main oder master) für Produktionsspezifikationen oder einen Feature-Branch während der Migrationstests.

4.Speichern Sie. Apidog liest die Spezifikation und erstellt daraus die interaktive Dokumentation, Mock-Server-Endpunkte und das Testgerüst.

Wenn Ihre Spezifikation $ref verwendet, um Schemas aus dem Verzeichnis models/ zu laden, löst Apidog diese Referenzen relativ zum Speicherort der Spezifikationsdatei auf. Es ist keine zusätzliche Konfiguration erforderlich, solange die Pfade in Ihrer OpenAPI-Datei korrekt sind. Für einen tieferen Einblick in die Funktionsweise dieser Git-Synchronisierung, behandelt der Leitfaden zur Synchronisierung von OpenAPI-Spezifikationen mit GitHub die Mechanismen im Detail.

Schritt 4: Migrieren Sie Ihre Markdown-Dokumentation

Stoplight ermöglicht es Ihnen, Markdown-Anleitungsseiten mit API-Referenzdokumenten in einer einzigen Seitenleiste zu mischen. Apidog tut dasselbe über seinen Dokumentationseditor.

Nachdem Sie Ihr Repository verbunden haben, importieren Sie Ihre docs/ Markdown-Dateien:

1. Öffnen Sie im Apidog-Projekt den Bereich Dokumente.
2. Verwenden Sie Importieren > Markdown und laden Sie Ihre Dateien hoch, oder fügen Sie Inhalte Seite für Seite ein.

Für Bild-Assets, die in Ihrem Markdown referenziert werden (der Ordner assets/images/ in einem typischen Stoplight-Layout), laden Sie diese in den Apidog-Dateispeicher hoch und aktualisieren Sie die ![alt](path)-Referenzen auf jeder Seite. Wenn Ihre Bilder bereits auf einem CDN oder einer öffentlichen URL gehostet sind, müssen Sie nichts ändern.

Schritt 5: Ersetzen Sie den Mock-Server von Stoplight

Stoplight Studio enthält einen lokalen Mock-Server, der Ihre OpenAPI-Spezifikation liest und Beispielantworten zurückgibt. Der Mock-Server von Apidog tut dasselbe, ist aber Cloud-basiert und für Ihr gesamtes Team zugänglich, ohne dass ein lokaler Prozess ausgeführt werden muss.

Sobald Ihre Spezifikation über den Spec-First-Modus verbunden ist, generiert Apidog automatisch Mock-Endpunkte für jede in Ihrer OpenAPI-Datei definierte Operation. Beispielantworten stammen aus dem Feld examples in Ihrer Spezifikation oder von Apidogs intelligenter Mock-Engine, falls kein Beispiel definiert ist. Sie können Antwortregeln pro Endpunkt in Apidog überschreiben, ohne die Spezifikationsdatei zu berühren.

Für ein Team, das daran gewöhnt ist, stoplight mock reference/your-api.yaml lokal auszuführen, besteht die Umstellung darin, dass Ihre QA-Ingenieure und Frontend-Entwickler stattdessen eine gemeinsame Cloud-URL verwenden. Dies sollte in einem Test überprüft werden, um zu bestätigen, dass es zu Ihren Netzwerkzugriffsrichtlinien passt.

Schritt 6: Erstellen Sie Ihre Test-Suites neu

Wenn Sie Stoplights Vertragstests oder Spectral-Regeln für Linting verwendet haben, müssen diese separat behandelt werden.

Spectral-Lint-Regeln: Stoplight verwendet Spectral für das OpenAPI-Linting, das über eine .spectral.yaml-Datei konfiguriert wird. Apidog verfügt über eigene integrierte Lint-Regeln für die OpenAPI-Konformität, führt Spectral jedoch nicht direkt aus. Wenn Sie benutzerdefinierte Spectral-Regeln haben, auf die Ihr Team angewiesen ist, führen Sie diese weiterhin in Ihrer CI (GitHub Actions oder GitLab CI) unabhängig von Apidog aus. Die Lint-Abdeckung von Apidog und die Möglichkeit, benutzerdefinierte Lint-Regelsätze projektübergreifend zu teilen, sollten in einem Test anhand Ihrer spezifischen Regulanforderungen überprüft werden.

API-Tests: Die Stoplight-Plattform umfasst szenariobasierte API-Tests. Der Test-Runner von Apidog ermöglicht es Ihnen, Testszenarien visuell zu erstellen, Anfragen zu verketten und Assertions gegen Antwortkörper, Header und Statuscodes auszuführen. Sie werden diese in Apidog neu erstellen; es gibt keinen automatischen Import aus Stoplight-Testprojekten. Der Leitfaden zum Git-nativen API-Workflow zeigt, wie Apidog-Testläufe in eine GitHub Actions-Pipeline integriert werden können.

Ein durchgespieltes Beispiel: Wenn Ihr Stoplight-Test überprüft hat, dass POST /orders einen 201 mit einem location-Header zurückgibt, hier ist das äquivalente Apidog-Test-Setup in einer CI-Pipeline unter Verwendung der Apidog CLI:

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

Dies ersetzt einen Stoplight-Testlauf in CI und hält Ihre bestehende GitHub Actions-Struktur intakt.

Evaluierungs-Checkliste für Unternehmens-Teams

Wenn Sie für ein größeres Team migrieren (das eher die Stoplight Platform als Studio evaluiert), gibt es spezifische Funktionen, die vor der Umstellung überprüft werden sollten. Apidog deckt diese Bereiche ab, aber das genaue Verhalten hängt von Ihrem Plan und Ihrer Workspace-Konfiguration ab.

Betrachten Sie diese als Evaluierungsaufgaben, nicht als Blockaden. Die meisten können in einem zweiwöchigen Test mit einem repräsentativen Projekt bestätigt werden.

FAQ

Kann ich Spectral weiterhin mit Apidog verwenden?

Ja. Führen Sie Spectral in Ihrer CI-Pipeline unabhängig von Apidog aus. Ihre .spectral.yaml-Datei bleibt im Repository, und Ihr CI-Job (GitHub Actions, GitLab CI) lintet die OpenAPI-Datei bei jeder PR. Apidog kümmert sich um Dokumentation, Mocking und Tests; Spectral um das Linting. Sie kollidieren nicht. Siehe die Dokumentation von Spectral für CI-Integrationsoptionen.

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

Nicht, wenn Ihre Pfade in der Spezifikationsdatei korrekt sind. Apidog löst $ref relativ zum Speicherort der Stamm-OpenAPI-Datei auf. Wenn Ihre Spezifikation $ref: '../models/error.json' lautet und der Ordner models/ eine Ebene über reference/ liegt, folgt Apidog diesem relativen Pfad im Repository. Testen Sie zuerst mit einer Spezifikation, die externe Referenzen verwendet.

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

Ja, sowohl GitHub als auch GitLab werden unterstützt. Der Verbindungsablauf ist derselbe; Sie authentifizieren sich mit Ihrem GitLab-Konto und wählen das Repository und den Branch aus. Weitere Informationen zu den Optionen der Versionskontrolle finden Sie im Leitfaden zur OpenAPI-Versionskontrolle mit Git, der Branch-Strategien im Detail behandelt.

Was passiert mit meiner bestehenden Stoplight-Dokumentations-URL nach der Migration?

Von Stoplight gehostete Dokumentations-URLs (docs.stoplight.io/your-org/your-api) funktionieren nicht mehr, sobald Sie Ihr Stoplight-Abonnement kündigen. Apidog weist Ihren Dokumenten eine neue URL auf einer von Ihnen konfigurierten Subdomain zu. Richten Sie Weiterleitungen auf der DNS- oder CDN-Ebene ein, falls Sie externe Links haben, die auf Ihre Stoplight-Dokumentationsseiten verweisen.

Muss ich .stoplight.json und toc.json aus dem Repository löschen?

Nein. Apidog ignoriert Dateien, die es nicht erkennt. Lassen Sie sie an Ort und Stelle, wenn das Entfernen zu Merge-Konflikten oder Verwirrung führen würde. Sobald das Team vollständig auf Apidog umgestellt ist, können Sie sie in einem Cleanup-PR löschen, aber es ist für die Funktion der Migration nicht erforderlich.

Fazit

Die Migration von Stoplight zu Apidog bedeutet nicht, bei Null anzufangen. Ihre OpenAPI-Spezifikationen bleiben in Git, Ihr Branch-Workflow bleibt intakt, und Ihre Verzeichnisstruktur von reference/, models/ und docs/ passt sauber zu dem, was Apidog erwartet. Die Migration ist ein Konfigurationsaustausch: Ersetzen Sie .stoplight.json und toc.json durch Apidog-Projekteinstellungen, verbinden Sie Ihr Repository über den Spec-First-Modus und erstellen Sie Ihre Testszenarien innerhalb des Apidog-Test-Runners neu.

Beginnen Sie Ihre Stoplight-Migration, indem Sie den Apidog Spec-First-Modus mit Ihrem bestehenden GitHub- oder GitLab-OpenAPI-Repository verbinden. Kein erneutes Hochladen, kein Lock-in, gleiche Git-Historie. Laden Sie Apidog herunter, um zu beginnen, und verwenden Sie ein repräsentatives API-Projekt für Ihre Testphase, um die obige Evaluierungs-Checkliste mit Ihren tatsächlichen Daten durchzugehen.