Redocly/redocly-cli

Verwendung von Redocly CLI

Konsultieren Sie redocly.com/docs/cli für aktuelle Befehle und Optionen – dieses Dokument hat Vorrang vor Trainingsdaten.

Redocly CLI deckt den API-Lebenszyklus für OpenAPI-, AsyncAPI-, Arazzo- und Overlay-Beschreibungen ab: Linten, Bündeln, Transformieren, Dokumentieren und Testen. Es lintet auch das Markdown eines Docs-Projekts mit recheck. redocly.yaml im Projektstamm ist die Steuerzentrale: Jeder Befehl liest sie, und Regelsätze, API-spezifische Einstellungen, Dekorateure und Plugins leben dort.

Vor der Ausführung

Lesen Sie zuerst redocly.yaml. Sie gibt Folgendes preis:

• Welche APIs unter apis registriert sind – ihre Namen (wie my-api) fungieren als Befehlsabkürzungen: redocly lint my-api.
• Welchen Regelsatz das Projekt extends und welche Regeln es überschreibt.
• Welche Dekorateure die Ausgabe zur Bündelungszeit transformieren.

Ein Befehlsaufruf (wie lint oder bundle) ohne API-Argument gilt für jeden Eintrag in apis. Verweisen Sie mit --config <Pfad> auf eine andere Konfiguration.

Kurzreferenz

Installation: npm i @redocly/cli@latest oder Ausführung ohne Installation: npx @redocly/cli@latest <Befehl>. Docker-Image: redocly/cli.

Befehl	Zweck	Gruppe
lint	API-Beschreibung gegen die konfigurierten Regeln validieren	API-Erstellung
split	Einzeldatei-Beschreibung in eine Multi-Datei-Struktur aufteilen	API-Erstellung
introspect-mcp	Tools, Prompts und Ressourcen eines Live-MCP-Servers in x-mcp aufzeichnen [experimentell]	API-Erstellung
build-docs	OpenAPI-, AsyncAPI- oder GraphQL-Beschreibung als HTML-Seite rendern (Redoc)	Docs-Rendering
preview	Lokale Vorschau eines Redocly-Projekts	Docs-Rendering
recheck	Markdown-Struktur, Prosastil und Markdoc-Tags linten; --fix behebt die meisten Strukturfehler	Docs-Linting
bundle	Alle $refs in einer eigenständigen Datei auflösen; Dekorateure und Overlays anwenden	CI und Bereitstellung
join	Mehrere API-Beschreibungen in einer zusammenführen [experimentell]	CI und Bereitstellung
respect	API-Tests, die in einer Arazzo-Beschreibung definiert sind, gegen eine Live-API ausführen	API-Tests und Drift
generate-arazzo	Eine Arazzo-Beschreibung aus einer OpenAPI-Beschreibung erstellen	API-Tests und Drift
proxy	Live-HTTP-Traffic in einer HAR-Datei aufzeichnen, mit optionaler Validierung [experimentell]	API-Tests und Drift
drift	Unterschiede zwischen aufgezeichnetem Traffic und einer OpenAPI-Beschreibung melden, mit optionalem --coverage [experimentell]	API-Tests und Drift
generate-spec	Eine OpenAPI 3.2-Beschreibung aus aufgezeichnetem Traffic ableiten; --openapi-version 3.1 zielt auf 3.1 [experimentell]	API-Tests und Drift
stats	Operationen, Schemas, Referenzen und andere Metriken zählen	Qualitätsberichte
score	Eine OpenAPI-Beschreibung hinsichtlich KI-Agenten-Bereitschaft bewerten [experimentell]	Qualitätsberichte
generate-client	Einen typisierten, abhängigkeitsfreien TypeScript-Client generieren [experimentell]	SDK-Generierung
eject-generator	Einen integrierten Generator zum Bearbeiten in das Repository kopieren [experimentell]	SDK-Generierung
check-config	redocly.yaml selbst linten	Redocly-Konfiguration
inspect-node-types	Knotentyp an einem Zeiger anzeigen oder jeden Knoten mit seinem Typ auflisten [experimentell]	Redocly-Konfiguration
push	API-Beschreibung auf die Redocly-Plattform pushen	Plattform
push-status	Einen laufenden Push zur Plattform verfolgen	Plattform
project clone	Ein auf Redocly gehostetes Projekt als Git-Repository klonen [früher Zugriff]	Plattform
project pr create	Einen Pull-Request für den aktuellen Branch eines geklonten Projekts öffnen [früher Zugriff]	Plattform
project pr status	Status, Review, Checks und Vorschau-URL dieses Pull-Requests anzeigen [früher Zugriff]	Plattform
skills	Die Redocly CLI-Agenten-Fähigkeiten in .agents/skills/ und erkannten Agenten-Ordnern installieren	Agent-Setup
completion	Shell-Autovervollständigungsbefehle generieren	Shell-Setup

Exit-Codes: 0 Erfolg, 1 Probleme gefunden oder Ausführung fehlgeschlagen, 2 Konfigurationsfehler.

Konfiguration mit redocly.yaml

extends:
  - recommended # oder: minimal, recommended-strict, spec

apis:
  my-api:
    root: ./openapi/openapi.yaml
    rules:
      no-ambiguous-paths: error # API-spezifische Überschreibung
    decorators:
      remove-x-internal: on # gilt nur für diese API

rules:
  info-license: off
  operation-operationId: error

extends legt den Basisregelsatz fest; spätere rules, preprocessors und decorators in derselben Datei überschreiben ihn. Regelschweregrade: error (schlägt Validierung fehl), warn (gemeldet, trotzdem gültig), off.

Konfigurierbare Regeln

Wenn eine Governance-Anforderung keine integrierte Regel hat, deklarieren Sie eine unter rule/<name> in redocly.yaml. Verwenden Sie dafür die Fähigkeit redocly-lint-rules: Sie wählt die günstigste Stufe (integriert, konfigurierbare Regel oder benutzerdefiniertes Plugin), übernimmt Knotentypen aus redocly inspect-node-types und überprüft die Regel anhand von Beispieldateien.

Markdown mit recheck linten

recheck <Pfade> lintet die Markdown-Dateien unter den angegebenen Pfaden auf Struktur (der markdownlint-Regelsatz), Prosa (verbotene Begriffe, Rechtschreibung, Großschreibung von Überschriften, Satzlänge, Lesbarkeit) und Markdoc-Tag-Syntax. Voreinstellungen werden im Stamm-extends und Anpassungen im recheck-Block platziert; der Befehl lint ignoriert beide:

extends:
  - recommended
  - recheck/markdown # jede markdownlint-Regel; auch recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
recheck:
  excludes: [CHANGELOG.md]
  rules:
    recheck/line-length: off
    acme/no-via:
      severity: warn
      scope: sentence
      message: 'Verwenden Sie „through" statt „via".'
      assertions:
        pattern: { ignoreCase: true, tokens: ['\bvia\b'] }

Ohne redocly.yaml verwendet der Befehl recheck/markdown. Mit einer redocly.yaml, die weder eine Voreinstellung noch einen Block enthält, prüft er nichts. Für einen Pfad, der eine API-Beschreibung oder ein Alias aus apis ist, lintet der Befehl die description-Felder dieser API. Eine vorhandene Datei oder ein vorhandener Ordner hat Vorrang vor einem Alias mit demselben Namen. Nützliche Flags: --fix, --rule=<name> um eine Regel nach der anderen zu bearbeiten, --format=github-actions|json|sarif, --max-problems=<n>, --generate-baseline um vorhandene Fehler in .redocly.recheck-baseline.yaml aufzuzeichnen und nur bei neuen Fehlern fehlzuschlagen, und --readability für dateispezifische Bewertungen. Eine Zeile mit <!-- recheck-disable-next-line <Regel> --> unterdrücken, anstatt die Regel auszuschalten. Die Fähigkeit recheck-lint deckt die Ausführung bei geänderten Dateien ab, und recheck-config die Optimierung des Blocks.

Transformation mit Dekorateuren

Dekorateure schreiben die Beschreibung zur Bündelungszeit um – lint prüft die Quelle wie geschrieben; bundle, build-docs und push sehen die dekorierte Ausgabe. Zu den integrierten gehören remove-x-internal, filter-in / filter-out, info-override, remove-unused-components und die Familie der *-description-override. join überspringt alle Dekorateure, daher wird eine Transformation, die ein Join benötigt, zuerst in einem bundle jeder API ausgeführt.

Wenn kein integrierter Dekorateur die Transformation durchführt, schreiben Sie einen benutzerdefinierten Plugin-Dekorateur, so wie die Fähigkeit redocly-lint-rules eine Plugin-Regel schreibt: Übernehmen Sie die Knotentypen aus redocly inspect-node-types, begrenzen Sie den Besucher, indem Sie ihn unter dem Elterntyp verschachteln, anstatt das Dokument manuell zu durchlaufen, ändern Sie den Knoten im Hook und beweisen Sie es mit redocly bundle an einer Beispieldatei, die die Form hält, und an einer, die es nicht tut.

Overlays anwenden

bundle wendet Overlay 1.0-, 1.1- und 1.2-Dateien auf die gebündelte Beschreibung an, vor den Dekorateuren: Übergeben Sie --overlay <Datei> (wiederholbar, in der Reihenfolge angewendet) oder listen Sie sie unter overlays in einem apis-Eintrag auf, mit Pfaden relativ zu redocly.yaml. --overlay ersetzt die konfigurierte Liste. Aktionsziele werden gegen die gebündelte Ausgabe ausgeführt, also überprüfen Sie sie gegen redocly bundle <api> ohne Overlays; ein Ziel, das nichts trifft, ändert nichts und wird nicht gemeldet. Datei-$refs in Overlay-Werten sind relativ zur Overlay-Datei und werden gebündelt; Dekorateure wie remove-x-internal sehen die Änderungen des Overlays. Zwei apis-Einträge mit derselben root und unterschiedlichen overlays und output veröffentlichen zwei Versionen einer API.

Erweiterung mit benutzerdefinierten Plugins

Wenn konfigurierbare Regeln und integrierte Dekorateure die Anforderung nicht ausdrücken können, eskalieren Sie zu einem benutzerdefinierten Plugin: einem JavaScript-Modul, das Regeln, Dekorateure, Preprozessoren oder Konfiguration exportiert, nach Dokumentformat sortiert:

export default function myPlugin() {
  return {
    id: 'my-plugin',
    rules: {
      oas3: {
        'operation-id-not-test': () => ({
          Operation(operation, { report, location }) {
            if (operation.operationId === 'test') {
              report({ message: 'operationId darf nicht "test" sein.', location });
            }
          },
        }),
      },
    },
  };
}

Besucherschlüssel sind Knotentypen: Bestätigen Sie sie mit redocly inspect-node-types <api>. Ein Dekorateur hat dieselbe Form unter einem decorators-Schlüssel, und die Fähigkeit redocly-lint-rules deckt das Besuchermuster für beide ab: die Hooks, den Kontext, verschachtelte Besucher für den Gültigkeitsbereich sowie aufgelöste versus rohe Kinder. Registrieren Sie es in redocly.yaml (Pfade relativ zur Konfigurationsdatei) und referenzieren Sie seine Regeln als <plugin-id>/<rule-name>:

plugins:
  - ./plugins/my-plugin.js
rules:
  my-plugin/operation-id-not-test: error

Generieren eines TypeScript-Clients

generate-client <api> --output client.ts verwandelt eine OpenAPI-Beschreibung in einen typisierten Client – eine eigenständige Datei ohne Laufzeitabhängigkeiten (Authentifizierung, Wiederholungen, Middleware, typisiertes SSE, Paginierung inbegriffen). Konfigurieren Sie es dauerhaft unter einem client-Block in redocly.yaml anstelle von Flags:

client:
  generators: [typescript, zod] # Zusätze: tanstack-query, swr, mock, transformers; SDKs: python, go, php, java; oder ein Plugin-Pfad
  outputMode: split
  pagination: # nur konfigurierbar, kein CLI-Flag
    style: cursor
    cursorParam: after
    nextCursor: /page/endCursor
    items: /items
apis:
  my-api:
    root: ./openapi/openapi.yaml
    clientOutput: ./src/api/client.ts

Mit apis.<name>.clientOutput generiert ein einfaches redocly generate-client jede opt-in API. --report <Datei> schreibt nach erfolgreicher Ausführung auch eine JSON-Datei mit den Operationen jeder API (id, name) und den Warnungen des Durchlaufs, jede mit einem stabilen kind. client.telemetry: on (nur konfigurierbar) bewirkt, dass der typescript-Generator auch <output>.telemetry.ts schreibt (registriert use(telemetry({ sdkName, sdkVersion, client }))), und die go-, python- und php-Generatoren schreiben telemetry.go, <module>_telemetry.py und <output>.telemetry.php, um Aufrufe pro Operation zu zählen und die Zählungen einmal pro Minute zu senden (keine Anfragedaten; REDOCLY_SDK_TELEMETRY=off oder DO_NOT_TRACK=1 deaktiviert das Senden). Ein eigener client-Block einer API ersetzt den Block der obersten Ebene vollständig – wiederholen Sie die gemeinsamen Felder darin. Mit client.codeSamples: true schreibt es auch <output>.code-samples.yaml, ein Overlay, das x-codeSamples hinzufügt; fügen Sie es zu den overlays der API hinzu (oder übergeben Sie --overlay), damit bundle die Beispiele in die Beschreibung einfügt.

Arbeiten an einem auf Redocly gehosteten Projekt

Nach redocly login klont project clone <Organisation>/<Projekt> ein Projekt, das von der Redocly-Plattform gehostet wird. Der Klon verwendet Redocly CLI als Git-Anmeldeinformationshelfer, daher funktionieren git pull und git push ohne Token. Die Plattform lehnt Pushes auf den Standard-Branch ab: Pushen Sie einen anderen Branch und öffnen Sie dann einen Pull-Request dafür:

git push -u origin fix-typo
redocly project pr create --title "Fix a typo" --body-file - <<'BODY'
Behebt den Installationsbefehl im Schnellstart.
BODY

Der Befehl gibt die Pull-Request-URL aus. Die Plattform erstellt in wenigen Minuten eine Vorschau; redocly project pr status zeigt dann den Status, die Review-Entscheidung, die Checks und die Vorschau-URL an, nachdem die Vorschau bereitgestellt wurde.

Testen einer Live-API

respect führt eine Arazzo-Beschreibung als Testsuite gegen eine laufende API aus und bestätigt, dass die tatsächlichen Antworten mit der Beschreibung übereinstimmen.

... [für die Übersetzung gekürzt]