Blog

Redocly Tutorial: Redocly CLI richtig nutzen

Mark Ponomarev

Mark Ponomarev

9 June 2025

Redocly Tutorial: Redocly CLI richtig nutzen

Willkommen zu diesem umfassenden Tutorial zur Redocly CLI! Redocly CLI ist ein leistungsstarkes All-in-One-Befehlszeilen-Tool für OpenAPI- und Swagger-Definitionen. Es hilft Ihnen beim Erstellen, Verwalten und Überprüfen der Qualität Ihrer API-Beschreibungen während des gesamten API-Lebenszyklus. Egal, ob Sie Entwickler, technischer Redakteur oder API-Produktmanager sind, dieses Tool bietet etwas für Sie.

Dieses Tutorial soll einen tiefen Einblick in die Redocly CLI geben und Sie vom Anfänger zum sicheren Benutzer machen. Wir werden alles behandeln, von der Installation bis hin zu erweiterten Funktionen wie benutzerdefinierten Linting-Regeln und CI/CD-Integration. Am Ende dieses Tutorials werden Sie in der Lage sein, die Redocly CLI in Ihren täglichen Workflow zu integrieren, um die Qualität Ihrer API und Dokumentation zu verbessern.

💡
Möchten Sie ein großartiges API-Testtool, das schöne API-Dokumentation generiert?

Möchten Sie eine integrierte All-in-One-Plattform für Ihr Entwicklerteam, um mit maximaler Produktivität zusammenzuarbeiten?

Apidog erfüllt all Ihre Anforderungen und ersetzt Postman zu einem deutlich günstigeren Preis!
Schaltfläche

Was ist Redocly CLI?

Wie in der offiziellen Dokumentation beschrieben, ist Redocly CLI Ihr "All-in-One OpenAPI-Dienstprogramm". Es unterstützt OpenAPI 3.1, 3.0, 2.0 (älteres Swagger), AsyncAPI und mehr. Es wurde entwickelt, um Ihnen bei Folgendem zu helfen:

Dieses Tool wurde mit Blick auf Leistung und Benutzererfahrung entwickelt und bietet schnelle Ausführung und menschenlesbare Fehlermeldungen.

Warum Redocly CLI verwenden?

In der heutigen API-First-Welt ist die Aufrechterhaltung hochwertiger API-Definitionen entscheidend. Redocly CLI hilft Ihnen dabei, dies zu erreichen, indem es:

Was dieses Tutorial behandeln wird

Dieses Tutorial ist als Schritt-für-Schritt-Anleitung zur Beherrschung der Redocly CLI aufgebaut. Folgendes werden wir behandeln:

Legen wir los!

Kapitel 1: Erste Schritte mit Redocly CLI

Dieses Kapitel führt Sie durch die ersten Schritte der Verwendung von Redocly CLI, von der Installation bis zur Ausführung Ihres ersten Befehls.

Voraussetzungen

Stellen Sie vor dem Start sicher, dass Folgendes auf Ihrem System installiert ist:

Installation

Sie haben mehrere Optionen, Redocly CLI zu installieren und zu verwenden. Wählen Sie diejenige, die am besten zu Ihren Anforderungen passt.

Verwendung von npx (Empfohlen für die schnelle Nutzung)

Wenn Sie Redocly CLI nur ohne globale Installation ausprobieren möchten, können Sie npx, den npm-Paket-Runner, verwenden. Dieser Befehl lädt die neueste Version von Redocly CLI herunter und führt sie aus.

npx @redocly/cli@latest --version

Um einen beliebigen redocly-Befehl zu verwenden, stellen Sie einfach npx @redocly/cli@latest voran. Zum Beispiel:

npx @redocly/cli@latest lint openapi.yaml

Dies ist eine großartige Möglichkeit, Redocly CLI in CI/CD-Umgebungen zu verwenden oder wenn Sie Ihr System nicht mit globalen Paketen überladen möchten.

Globale Installation mit npm

Für den regelmäßigen Gebrauch ist eine globale Installation bequemer. Sie macht den Befehl redocly direkt in Ihrem Terminal verfügbar.

npm install -g @redocly/cli@latest

Nach der Installation können Sie dies überprüfen, indem Sie die Version abfragen:

redocly --version

Jetzt können Sie Befehle wie diesen ausführen:

redocly lint openapi.yaml

Verwendung von Docker

Wenn Sie Docker bevorzugen, stellt Redocly ein vorgefertigtes Docker-Image bereit. Dies ist nützlich, um das Tool von Ihrer lokalen Umgebung zu isolieren.

Ziehen Sie zunächst das Image von Docker Hub:

docker pull redocly/cli

Um einen Befehl auszuführen, müssen Sie Ihr aktuelles Arbeitsverzeichnis (wo sich Ihre API-Dateien befinden) als Volume in den Docker-Container einbinden.

docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml

In diesem Befehl bezieht sich $PWD auf Ihr aktuelles Verzeichnis, das in das Verzeichnis /spec innerhalb des Containers eingebunden wird. Sie müssen dann auf Ihre Dateien über den Pfad /spec verweisen.

Grundlegende Befehlsstruktur

Die grundlegende Struktur zur Verwendung von Redocly CLI ist:

redocly [Befehl] [Argumente] [Optionen]

Sie können jederzeit Hilfe zu einem bestimmten Befehl erhalten, indem Sie die Option --help verwenden:

redocly lint --help

Nachdem Sie Redocly CLI installiert haben und die grundlegende Befehlsstruktur verstehen, fahren wir mit der Erkundung seiner leistungsstarken Funktionen fort.

Kapitel 2: Kernbefehle und -funktionen

Dieses Kapitel behandelt die Kernbefehle der Redocly CLI. Wir werden untersuchen, wie Sie Ihre API-Definitionen linten, verwalten, dokumentieren und analysieren können. Für die Beispiele in diesem Kapitel verwenden wir eine einfache Datei namens openapi.yaml.

Erstellen wir eine Datei namens openapi.yaml mit folgendem Inhalt:

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Abschnitt 2.1: Linting Ihrer API-Beschreibungen (lint)

API-Linting ist der Prozess der Überprüfung Ihrer API-Definitionsdatei auf Konsistenz, Korrektheit und Stil. Es hilft Ihnen, API-Designrichtlinien durchzusetzen und potenzielle Probleme zu erkennen, bevor sie in Produktion gehen.

Grundlegende Verwendung

Der Befehl lint wird verwendet, um Ihre API-Definition anhand einer Reihe von Regeln zu überprüfen.

redocly lint openapi.yaml

Standardmäßig verwendet redocly lint das Regelwerk recommended. Wenn unsere openapi.yaml Probleme aufweist, werden diese im Output detailliert aufgeführt. Für unsere Beispieldatei sollte der Output wie folgt aussehen:

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

Konfigurieren von Regeln

Redocly CLI wird mit drei integrierten konfigurierbaren Regelwerken geliefert:

Sie können ein Regelwerk mit der Option --extends angeben:

redocly lint openapi.yaml --extends=minimal

Sie können auch eigene benutzerdefinierte Regelwerke in einer Konfigurationsdatei namens redocly.yaml erstellen. Dies werden wir in Kapitel 3 behandeln.

Output-Formate

Der Befehl lint unterstützt verschiedene Output-Formate mit der Option --format, was sehr nützlich für die Integration mit anderen Tools ist.

Beispiel für die Verwendung des Formats stylish:

redocly lint openapi.yaml --format=stylish

Probleme ignorieren

Manchmal müssen Sie ein bestimmtes Problem ignorieren. Sie können eine Datei namens .redocly.lint-ignore.yaml generieren, um Fehler und Warnungen zu unterdrücken.

redocly lint openapi.yaml --generate-ignore-file

Dieser Befehl erstellt eine Ignore-Datei. Wenn Sie lint erneut ausführen, werden die in dieser Datei aufgeführten Probleme ignoriert. Dies gibt Ihnen eine detaillierte Kontrolle über den Linting-Prozess.

Abschnitt 2.2: Verwalten von API-Beschreibungen mit bundle und split

Wenn Ihre API wächst, wird die Verwaltung einer einzelnen, monolithischen OpenAPI-Datei umständlich. Redocly CLI bietet zwei Befehle, um dabei zu helfen: split und bundle.

Aufteilen einer großen OpenAPI-Datei (split)

Der Befehl split ermöglicht es Ihnen, eine große API-Definitionsdatei in eine besser verwaltbare Struktur aus mehreren Dateien aufzuteilen. Er extrahiert Komponenten, Pfade und Beispiele in separate Dateien und Ordner.

Teilen wir unsere openapi.yaml auf:

redocly split openapi.yaml --outDir=split-api

Dieser Befehl erstellt ein Verzeichnis namens split-api mit folgender Struktur:

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

Die neue openapi.yaml in split-api wird nun $ref verwenden, um auf die externen Dateien zu verlinken:

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

Dies erleichtert die Verwaltung verschiedener Teile Ihrer API erheblich.

Bündeln mehrerer Dateien (bundle)

Der Befehl bundle macht das Gegenteil von split. Er nimmt eine Root-API-Definitionsdatei und löst alle lokalen $refs auf, um eine einzelne, in sich geschlossene Datei zu erstellen. Dies ist nützlich für Tools, die keine Definitionen aus mehreren Dateien unterstützen.

Bündeln wir unsere aufgeteilte API wieder zu einer einzigen Datei:

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

Die Datei bundled-api.yaml wird denselben Inhalt wie unsere ursprüngliche openapi.yaml haben.

Dereferenzierung

Der Befehl bundle kann auch eine vollständig dereferenzierte Datei erstellen, bei der alle $refs (einschließlich entfernter) aufgelöst und durch ihren Inhalt ersetzt werden.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

Dies kann nützlich sein, aber beachten Sie, dass dies die Datei erheblich vergrößern kann und dass zirkuläre Referenzen Probleme mit der JSON-Ausgabe verursachen können.

Abschnitt 2.3: Generieren von API-Dokumentation (build-docs)

Eine der leistungsstärksten Funktionen der Redocly CLI ist die Fähigkeit, schöne, interaktive API-Referenzdokumentation mit der Open-Source-Engine Redoc zu generieren.

Grundlegende Verwendung

Um Dokumentation zu generieren, verwenden Sie den Befehl build-docs:

redocly build-docs openapi.yaml

Dies erstellt eine Datei namens redoc-static.html in Ihrem aktuellen Verzeichnis. Öffnen Sie sie in Ihrem Browser, um Ihre Dokumentation anzuzeigen.

Sie können eine andere Output-Datei mit der Option -o oder --output angeben:

redocly build-docs openapi.yaml -o my-api-docs.html

Anpassen des Outputs

Sie können das Aussehen und Verhalten Ihrer Dokumentation mit der Option --theme.openapi anpassen. Dies ermöglicht es Ihnen, Farben, Schriftarten und sogar Teile der Benutzeroberfläche wie die Suchleiste zu deaktivieren.

Um beispielsweise die Suchleiste zu deaktivieren:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

Alle verfügbaren Theme-Optionen finden Sie in der offiziellen Redocly-Dokumentation.

Für noch mehr Kontrolle können Sie Ihre eigene Handlebars-Vorlage bereitstellen, um die Dokumentation zu rendern. Dies ist eine erweiterte Funktion, die eine vollständige Anpassung des HTML-Outputs ermöglicht.

Abschnitt 2.4: Abrufen von API-Statistiken (stats)

Der Befehl stats liefert nützliche Metriken über Ihre API-Definition, wie z. B. die Anzahl der Pfade, Operationen, Schemas und mehr.

So erhalten Sie Statistiken

Um Statistiken für Ihre API zu erhalten, führen Sie einfach aus:

redocly stats openapi.yaml

Der Standard-Output ist im Format stylish:

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

Verschiedene Formate

Wie der Befehl lint unterstützt stats verschiedene Output-Formate mit der Option --format. Die Formate json und markdown sind besonders nützlich.

redocly stats openapi.yaml --format=json

Dies ist großartig, um die Statistiken in andere Tools oder Dashboards einzuspeisen.

redocly stats openapi.yaml --format=markdown

Dies generiert eine Markdown-Tabelle, die sich perfekt für Berichte oder für die Verwendung in GitHub Actions-Zusammenfassungen eignet, wie wir im nächsten Kapitel sehen werden.

Kapitel 3: Erweiterte Themen

In diesem Kapitel tauchen wir in einige der erweiterten Funktionen der Redocly CLI ein, einschließlich der leistungsstarken Konfigurationsdatei und der Integration mit CI/CD-Pipelines.

Konfigurationsdatei (redocly.yaml)

Während Sie Redocly CLI vollständig über die Befehlszeile verwenden können, ermöglicht Ihnen eine Konfigurationsdatei namens redocly.yaml, Ihre Konfiguration an einem Ort zu speichern, was Ihre Befehle kürzer und Ihre Konfiguration wiederverwendbar macht.

Erstellen wir eine Datei namens redocly.yaml im Root-Verzeichnis unseres Projekts:

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

Struktur der Konfigurationsdatei

Verwendung von API-Aliasen

Mit konfiguriertem Abschnitt apis können Sie nun den Alias main anstelle des Dateipfads in Ihren Befehlen verwenden:

redocly lint main
redocly stats main
redocly build-docs main

Dies ist besonders nützlich, wenn Sie mehrere APIs in Ihrem Projekt haben. Wenn Sie redocly lint ohne Argumente ausführen, lintet es alle im Abschnitt apis definierten APIs.

Kontinuierliche Integration (CI)

Die Integration von Redocly CLI in Ihre CI/CD-Pipeline ist eine fantastische Möglichkeit, API-Qualitätsprüfungen zu automatisieren. Hier ist ein Beispiel, wie Sie es mit GitHub Actions verwenden können.

Erstellen Sie eine Datei namens .github/workflows/redocly.yaml:

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

Dieser GitHub Actions-Workflow tut Folgendes:

  1. Er wird bei jedem Push und Pull Request an den Branch main ausgelöst.
  2. Er checkt Ihren Code aus.
  3. Er installiert Node.js und Redocly CLI.
  4. Er führt den Befehl lint mit dem Format github-actions aus. Dies wird automatisch alle Probleme direkt in Ihren Pull Requests annotieren.
  5. Er führt den Befehl stats mit dem Format markdown aus und hängt den Output an die Job-Zusammenfassung an, wodurch Sie bei jedem Lauf einen schönen Bericht erhalten.

Dies ist eine leistungsstarke Methode, um sicherzustellen, dass Ihre API-Definitionen immer in gutem Zustand sind.

Kapitel 4: Praktisches Beispiel: Ein vollständiger Workflow

In diesem letzten Kapitel fassen wir alles Gelernte zusammen und durchlaufen einen vollständigen, praktischen Workflow. Wir werden:

  1. Eine Projektstruktur mit einer API-Definition aus mehreren Dateien erstellen.
  2. Eine Konfigurationsdatei namens redocly.yaml erstellen.
  3. Die API-Definition anhand unserer benutzerdefinierten Konfiguration linten.
  4. Die API zu einer einzigen Datei bündeln.
  5. API-Dokumentation generieren.

1. Projekt-Setup

Erstellen wir ein neues Verzeichnis für unser Projekt und richten die Dateistruktur ein.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

Erstellen wir nun die aufgeteilten API-Dateien.

openapi/components/schemas/Pet.yaml:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml:

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (unser Haupt-Entrypoint):

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. Erstellen von redocly.yaml

Erstellen wir nun unsere Konfigurationsdatei im Root-Verzeichnis des Verzeichnisses redocly-petstore.

redocly.yaml:

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

In dieser Konfiguration haben wir einen Alias namens petstore@v1 für unsere API definiert und einige benutzerdefinierte Linting-Regeln hinzugefügt.

3. API linten

Linten wir nun unsere API anhand unserer neuen Konfiguration.

redocly lint petstore@v1

Sie werden einige Fehler und Warnungen sehen, da unsere API noch nicht allen unseren neuen Regeln entspricht. Zum Beispiel haben wir keine Tags mit Beschreibungen. Dies zeigt, wie Sie Ihren eigenen API-Styleguide durchsetzen können.

4. API bündeln

Als Nächstes bündeln wir unsere API aus mehreren Dateien zu einer einzigen verteilbaren Datei.

redocly bundle petstore@v1 -o dist/petstore.yaml

Dies erstellt ein Verzeichnis namens dist mit einer Datei namens petstore.yaml darin, die die vollständig aufgelöste API-Definition enthält.

5. Dokumentation generieren

Schließlich generieren wir unsere API-Dokumentation.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

Dies erstellt die Datei dist/petstore-docs.html. Öffnen Sie diese Datei in Ihrem Browser, um Ihre schöne, interaktive API-Dokumentation anzuzeigen.

Und das war's! Ein vollständiger Workflow von einer strukturierten API-Definition aus mehreren Dateien über eine gebündelte Datei bis hin zu professioneller Dokumentation, alles verwaltet mit Redocly CLI.

Fazit

In diesem Tutorial haben wir einen tiefen Einblick in die Redocly CLI erhalten. Wir begannen mit den Grundlagen der Installation und der Kernbefehle, gingen dann zu erweiterten Themen wie Konfiguration und CI-Integration über und durchliefen schließlich einen vollständigen, praktischen Workflow.

Sie sollten nun ein solides Verständnis dafür haben, wie Sie Redocly CLI verwenden, um:

Redocly CLI ist ein vielseitiges und leistungsstarkes Tool, das Ihren API-Entwicklungsworkflow erheblich verbessern kann. Ich ermutige Sie, seine Funktionen weiter zu erkunden und es in Ihre Projekte zu integrieren.

Weitere Ressourcen

Vielen Dank, dass Sie diesem Tutorial gefolgt sind. Viel Spaß beim API-Erstellen!

💡
Möchten Sie ein großartiges API-Testtool, das schöne API-Dokumentation generiert?

Möchten Sie eine integrierte All-in-One-Plattform für Ihr Entwicklerteam, um mit maximaler Produktivität zusammenzuarbeiten?

Apidog erfüllt all Ihre Anforderungen und ersetzt Postman zu einem deutlich günstigeren Preis!
Schaltfläche

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenDownload