Swagger CLI zu Apidog CLI migrieren

Wenn Sie `swagger-cli validate` und `swagger-cli bundle` immer noch in Ihrer Pipeline ausführen, pflegen Sie ein Skript um ein Tool herum, das niemand mehr wartet. Das swagger-cli GitHub-Repository gibt dies nun direkt an: Das Paket wird nicht mehr gepflegt, die README nennt die Last, mit einer riesigen Nutzerbasis Schritt zu halten, die wenig zurückgibt, und verweist neue Benutzer auf andere Lösungen.

Dies ist also ein guter Zeitpunkt, um zu entscheiden, wo Ihr Spezifikations-Workflow als Nächstes angesiedelt sein soll. Dieser Leitfaden ist ein Migrations-Runbook, kein Nutzungs-Tutorial. Wenn Sie noch nicht bereit sind zu wechseln und das alte Tool einfach weiterverwenden möchten, deckt der Swagger CLI-Leitfaden `validate` und `bundle` detailliert ab. Dieser Artikel handelt vom Abschied, genauer gesagt, wie Sie Swagger CLI zu Apidog CLI migrieren, ohne Ihre CI zu unterbrechen.

Laden Sie Apidog herunter, wenn Sie die echten Befehle ausprobieren möchten. Der Start ist kostenlos, keine Kreditkarte erforderlich.

Warum jetzt migrieren

Zuerst die ehrliche Antwort: swagger-cli ist seit einiger Zeit veraltet und wird nicht mehr gewartet. Es läuft immer noch. Viele Pipelines rufen es heute auf. Aber ein Tool, das keine Fehlerbehebungen oder Spezifikationsaktualisierungen erhält, ist technische Schuld, die in Ihrem Build steckt, und die Betreuer selbst empfehlen, weiterzuziehen.

Sie verweisen insbesondere auf einen Nachfolger. Redocly CLI ist der nächstgelegene Drop-in-Ersatz, wenn Sie im Terminal nur Validierung plus Bündelung wollten. Es ist Open Source, code-first und terminal-nativ. Sein `lint`-Befehl führt strukturelle Validierungen durch, und `redocly bundle` folgt den `$ref`-Pointern genau wie `swagger-cli bundle`. Wenn Ihr einziges Ziel ein 1:1-Austausch ist, der die Spezifikation als flache Datei in Ihrem Repository belässt, ist Redocly die natürliche Wahl, und Redocly veröffentlicht einen eigenen Migrationsleitfaden mit der Befehlszuordnung. Es ist keine Schande, diesen Weg zu gehen.

Apidog dient einem anderen Ziel. Migrieren Sie zu Apidog CLI, wenn die Spezifikation mehr tun soll, als nur in einer Datei zu liegen. Anstatt ein statisches Dokument zu validieren und zu bündeln, bringen Sie die gesamte Definition in einen lebendigen Arbeitsbereich, validieren sie dann beim Import, exportieren eine konsolidierte Datei, wenn Sie eine benötigen, und können optional die API mocken, Testszenarien dagegen ausführen und Dokumente aus derselben Quelle veröffentlichen. swagger-cli hat immer nur zwei Dinge getan. Apidog deckt den Rest des Lebenszyklus ab.

Wählen Sie nach Eignung, nicht nach Hype. Wenn Sie einen schlanken, konfigurationsgesteuerten Linter und Bundler wünschen, den Sie rein vom Terminal aus ausführen, gewinnt Redocly. Wenn Sie lieber eine einzige Plattform für Design, Mocking, Tests und Dokumente hätten, anstatt mehrere Tools zusammenzufügen, gewinnt Apidog.

Was swagger-cli tat vs. was Apidog CLI tut

swagger-cli hatte genau zwei Befehle:

• `swagger-cli validate <file>` überprüfte ein Swagger 2.0- oder OpenAPI 3.0-Dokument anhand des Schemas und verifizierte, dass seine `$ref`-Pointer aufgelöst wurden.
• `swagger-cli bundle <file>` folgte diesen `$ref`-Pointern und kombinierte eine Definition aus mehreren Dateien in eine einzige Datei, mit Optionen für den Ausgabepfad (`-o`), den Typ (`-t json|yaml`), die vollständige Dereferenzierung (`-r`) und die Einrückung (`-f`).

Das ist das ganze Tool. Es hat weder mit Stilregeln gelintet, noch Dokumente generiert, Tests ausgeführt oder irgendetwas gemockt.

Apidog CLI ordnet diese beiden Aufgaben zwei seiner Befehle zu und geht dann weiter:

• apidog import nimmt eine Definition in ein Apidog-Projekt auf und validiert sie dabei. Spezifikationen mit mehreren Dateien erhalten ihre `$ref`-Pointer automatisch in vereinheitlichte Ressourcen aufgelöst. Dies ist Ihr Validierungsschritt, plus Aufnahme.
• apidog export gibt eine einzelne konsolidierte Datei aus dem Projekt aus und lässt Sie die OpenAPI-Version beim Export wählen. Dies ist Ihr Bündelungsschritt, plus ein optionales Versionsupgrade und die Möglichkeit, HTML- oder Markdown-Dokumente auszugeben.
• apidog run führt Testszenarien und Suiten aus, mit JUnit und anderen Reportern für CI. swagger-cli hatte kein Äquivalent.
• Ressourcenbefehle (`endpoint`, `schema`, `mock`, `environment`, `branch` und mehr) verwalten das Projekt vom Terminal aus, sobald die Spezifikation vorhanden ist.

Ein präziser Punkt, damit die Zuordnung ehrlich bleibt: Apidog validiert die Struktur beim Import, ist aber kein konfigurierbarer Style-Guide-Linter. Es gibt keinen `apidog lint`-Befehl und keine benutzerdefinierten Regelsätze. Wenn Sie sich auf meinungsbildendes Linting verlassen haben, wird dieser Teil nicht übernommen, und der Abschnitt Was Sie gewinnen behandelt, wie damit umzugehen ist.

Installieren und Anmelden

Apidog CLI wird als npm-Paket ausgeliefert. Installieren Sie es global:

npm install -g apidog-cli@latest

Authentifizieren Sie sich dann mit einem Zugriffstoken:

apidog login --with-token <TOKEN>

Sie erhalten das Token aus der Apidog-App oder dem Web: Klicken Sie auf Ihr Avatar, gehen Sie zu Kontoeinstellungen, dann zu API-Zugriffstoken, und generieren Sie eines. Das CLI speichert es in `~/.apidog/config.toml`. Behandeln Sie es wie jedes andere Geheimnis. Drucken Sie es nicht in Protokollen aus oder committen Sie es in Ihr Repository.

Wenn Sie alle Flags und eine tiefere Tour wünschen, decken der vollständige Apidog CLI-Leitfaden und die offiziellen Apidog CLI-Dokumente die gesamte Oberfläche ab. Für diese Migration genügen Installation plus Anmeldung, um zu starten.

Befehlszuordnungstabelle

Hier ist die direkte Übersetzung von swagger-cli zu Apidog CLI. Der eine strukturelle Unterschied: Apidog arbeitet mit einem Projekt, sodass die meisten Abläufe Import-dann-Export sind, anstatt eines einzelnen Befehls für eine lose Datei.

Die beiden wichtigsten Zellen für die Migration sind die ersten beiden Zeilen. Alles darunter sind Funktionen, die swagger-cli nie hatte. Das Flag --oas-version ist das klarste Upgrade: swagger-cli konnte eine Swagger 2.0-Datei bündeln, aber sie nicht in OpenAPI 3.1 umwandeln. Apidog kann dies beim Export, was praktisch ist, wenn Sie einen alten Vertrag modernisieren. Wenn Ihr Ziel speziell die Dokumentenausgabe ist, behandelt das Exportieren von OpenAPI nach Markdown dieses Format ausführlicher.

Schritt-für-Schritt-Migration

Hier ist der vollständige Weg von einem swagger-cli-Setup zu einem funktionierenden Apidog-Flow.

1. Projekt-ID abrufen. Erstellen oder öffnen Sie ein Projekt in der Apidog-App. Die Projekt-ID wird in den Projekteinstellungen und in der URL angezeigt. Sie übergeben sie jedem CLI-Befehl über --project.

2. Root-Spezifikation importieren. Zeigen Sie Apidog auf die Einstiegsdatei Ihrer Definition. Spezifikationen mit mehreren Dateien und `$ref`-Pointern werden automatisch aufgelöst, sodass Sie die Root-Datei importieren und Apidog den Rest einbezieht:

apidog import --project 123456 --format openapi --file ./openapi.yaml

Wenn die Spezifikation fehlerhaft ist oder ein `$ref` undefiniert ist, schlägt der Import fehl. Dieser Fehler ist Ihr Validierungs-Gateway, dieselbe Aufgabe, die `swagger-cli validate` früher erledigte, jetzt in die Aufnahme integriert.

3. In der App überprüfen. Öffnen Sie das Projekt und bestätigen Sie, dass Ihre Endpunkte, Schemas und Parameter korrekt übernommen wurden. Diese visuelle Prüfung hat kein swagger-cli-Äquivalent, und es lohnt sich, sie einmal während der Migration durchzuführen, um zu bestätigen, dass der Import das getan hat, was Sie erwartet haben.

4. Die konsolidierte Datei exportieren. Wenn Sie eine einzelne, flache Datei benötigen (für ein nachgeschaltetes Tool, einen Client-Generator oder ein Artefakt), exportieren Sie diese. Wählen Sie die gewünschte OpenAPI-Version:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Das ersetzt `swagger-cli bundle`. Die `$ref`-Pointer wurden bereits beim Import aufgelöst, sodass der Export Ihre konsolidierte Ausgabe in einer einzigen Datei ist.

5. In CI integrieren. Ersetzen Sie Ihren alten `swagger-cli`-Schritt durch Import (Validierung bei Aufnahme) und Export (Bündelung) und fügen Sie einen Testlauf hinzu, falls Sie Szenarien haben. Der nächste Abschnitt enthält ein vollständiges GitHub Actions-Beispiel.

CI-Beispiel mit GitHub Actions

Dieser Workflow installiert die CLI, meldet sich mit einem Token aus den Repository-Secrets an, importiert die Spezifikation zur Validierung, exportiert ein konsolidiertes Artefakt und führt dann Testszenarien mit dem JUnit-Reporter aus, sodass ein fehlgeschlagener Test die Prüfung fehlschlagen lässt und den Pull Request blockiert.

name: API spec check

on:
  pull_request:
    branches: [main]

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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

Speichern Sie das Token als `APIDOG_ACCESS_TOKEN` in Ihren Repository-Secrets, damit es niemals in Protokollen erscheint. Der -r "cli,junit"-Reporter schreibt eine JUnit-XML-Datei, die Ihre CI als Testbericht anzeigen kann, und ein fehlschlagendes Szenario gibt einen Exit-Code ungleich Null zurück, der das Mergen blockiert. Für tiefere Pipeline-Muster siehe den Apidog CLI CI/CD-Leitfaden und für Runner-spezifisches Setup die Apidog CLI mit GitHub Actions-Anleitung.

Was Sie über Validierung und Bündelung hinaus gewinnen

Hier zahlt sich die Migration aus, und hier kommt es am meisten auf Ehrlichkeit an.

Mock-Server. Sobald Ihre Spezifikation in einem Projekt ist, kann Apidog Mock-Antworten daraus bereitstellen. Sie können ein Frontend gegen die API entwickeln, bevor das Backend existiert. swagger-cli hat niemals das Laufzeitverhalten berührt.

Automatisierte Testszenarien. apidog run führt echte Anfragen gegen eine laufende API aus und überprüft die Antworten. Sie erstellen Szenarien visuell in der App und führen sie dann headless in CI aus. Das schließt die Lücke, die swagger-cli weit offen gelassen hat: Eine gültige Spezifikation sagt Ihnen, dass der Vertrag wohlgeformt ist, nicht dass die Implementierung dazu passt.

Gehostete und exportierte Dokumente. apidog export --format html oder --format markdown erzeugt Dokumente direkt aus derselben Quelle. Kein separater Dokumenten-Build-Schritt zum Pflegen.

Nun zur ehrlichen Einschränkung. Apidog CLI verfügt nicht über einen konfigurierbaren, code-first Style-Guide-Linter mit benutzerdefinierten Regelsätzen. Es validiert die Struktur beim Import, aber Sie können keine Spectral- oder Redocly-ähnlichen Regeln über die CLI erstellen, und es gibt keinen apidog lint-Befehl. Wenn Ihr altes Setup stark auf Linting (konsistente Benennung, erforderliche Beschreibungen, Beispiele für jede Antwort) angewiesen war, halten Sie einen dedizierten Linter im Einsatz. Kombinieren Sie Apidog dafür mit Spectral oder Redocly und führen Sie es als separaten CI-Schritt aus. Der OpenAPI Linter Einrichtungsleitfaden behandelt, wie man einen integriert. Die Verwendung beider ist kein Widerspruch: Linting mit einem Spezialwerkzeug, dann den Lebenszyklus in Apidog verwalten.