Die meisten Tutorials zum API-Design beginnen mit einer Maus. Öffnen Sie einen visuellen Editor, ziehen Sie ein Schema auf eine Leinwand, klicken Sie sich durch Dialoge, um ein Feld hinzuzufügen. Das funktioniert, aber es passt nicht dazu, wie viele Teams tatsächlich ihre Produkte ausliefern. Wenn Ihre API-Definition in Git liegt, in Pull Requests überprüft wird und CI durchläuft, möchten Sie sie auf die gleiche Weise entwerfen, wie Sie sie bereitstellen: über das Terminal, in Textform, mit Befehlen, die Sie skripten können.
APIs über die Befehlszeile zu entwerfen bedeutet, dass Sie den Vertrag erstellen, ihn anhand eines Styleguides linten, ihn zu einer einzigen Datei bündeln und Stubs generieren – alles, ohne die Shell zu verlassen. Jeder Schritt ist wiederholbar. Jeder Schritt kann in einer Pipeline ausgeführt werden. Und wenn ein KI-Agent oder ein Teamkollege Ihr Setup reproduzieren muss, führen sie dieselben Befehle aus, die Sie ausgeführt haben, anstatt zu raten, welche Schaltflächen Sie geklickt haben.
Dieser Leitfaden beschreibt zwei Wege. Zuerst den allgemeinen Open-Source-Pfad, der aus spezialisierten Tools besteht: Erstellen Sie eine OpenAPI-Datei, linten Sie sie mit Spectral, bündeln Sie sie mit der Redocly CLI und generieren Sie Server-Stubs mit openapi-generator. Dann den Apidog CLI-Pfad, bei dem Design, Schemas, Endpunkte und Authentifizierung in einem einzigen Projekt leben, das Sie über das Terminal steuern können. Wenn Sie zuerst den tieferen konzeptionellen Hintergrund wünschen, lesen Sie unseren Leitfaden zu wie man eine API entwirft und die Anleitung zum Entwerfen von REST-APIs.
Wenn Sie Apidog folgen, besorgen Sie sich zuerst die Binärdatei. Unser Apidog CLI-Installationsleitfaden behandelt den Schritt npm install -g apidog-cli und den apidog login --with-token-Handshake, und der vollständige Apidog CLI-Leitfaden zeigt jede Befehlsgruppe auf.
Der allgemeine Open-Source-Weg: erstellen, linten, bündeln, generieren
Der klassische CLI-Design-Stack ist eine Reihe unabhängiger Tools, die Sie miteinander verbinden. Sie halten Ihre API-Definition in einer OpenAPI-Datei unter Versionskontrolle und führen jedes Tool als einen Schritt aus. Dies ist der Git-native API-Design-Workflow, und er ist wirklich gut. So sieht er aus.
Das OpenAPI-Dokument erstellen
Sie beginnen mit einer einfachen YAML-Datei. Es ist kein spezieller Editor erforderlich; jeder Texteditor funktioniert. Eine minimale openapi.yaml sieht so aus:
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: An order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
schemas:
Order:
type: object
required: [id, status]
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
Wenn die API wächst, teilen Sie sie auf mehrere Dateien auf und referenzieren diese mit $ref. Das hält jedes Schema für sich lesbar und überprüfbar.
Mit Spectral linten
Handgeschriebenes OpenAPI weicht ab. Jemand vergisst eine operationId, eine andere Person lässt eine Antwort undokumentiert, eine dritte erfindet ihre eigene Namenskonvention. Ein Linter fängt all das vor der Überprüfung ab. Spectral, von Stoplight, ist die Standardwahl. Es liefert Regelsätze für OpenAPI und ermöglicht es Ihnen, eigene zu schreiben.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral gibt jede Verletzung mit Zeilennummer und Schweregrad aus. Sie können den Build bei Fehlern fehlschlagen lassen, indem Sie den Exit-Code in CI überprüfen. Die Redocly CLI und vacuum erledigen die gleiche Aufgabe, wenn Sie eine Alternative wünschen; vacuum ist schnell und lässt sich als Spectral-kompatibler Linter einsetzen. Der Punkt bleibt bestehen, egal welchen Sie wählen: Linting ist ein separates, dediziertes Tool, und Sie führen es als eigenständigen Schritt aus.
Mit der Redocly CLI bündeln
Sobald Ihre Definition auf mehrere Dateien aufgeteilt ist, wünschen sich die meisten nachgelagerten Tools ein einziges, in sich geschlossenes Dokument. Die Redocly CLI löst jeden $ref auf und glättet den Baum in eine einzige Datei.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redocly lintet auch (redocly lint) und zeigt Dokumentationen in der Vorschau an, daher verwenden einige Teams es sowohl für die Stilprüfung als auch für das Bündeln. Die offizielle Dokumentation listet den vollständigen Befehlssatz auf.
Stubs mit openapi-generator generieren
Mit einer sauberen, gebündelten Spezifikation generieren Sie Code. openapi-generator verwandelt ein OpenAPI-Dokument in Server-Stubs, Client-SDKs und mehr in Dutzenden von Sprachen.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
Ersetzen Sie -g spring durch -g python-flask, -g go-server oder einen der unterstützten Generatoren. Jetzt haben Sie ein Gerüst, das genau Ihrem Vertrag entspricht.
Das ist der offene Weg von Anfang bis Ende: vier Tools, vier Befehle, alle skriptfähig. Der Preis ist die Verdrahtung. Sie pflegen das Dateilayout, die Linter-Konfiguration, den Bündelungsschritt und die Generator-Konfiguration selbst, und jedes Tool hat seine eigenen Konventionen. Es funktioniert gut, wenn Sie maximale Kontrolle wünschen und es Ihnen nichts ausmacht, die einzelnen Teile selbst zu verbinden.
Der Apidog CLI-Weg: Design in einem Projekt
Der andere Ansatz hält Design, Schemas, Endpunkte, Mocks und Authentifizierung innerhalb eines einzigen Projekts, das Sie vom Terminal aus steuern. Das apidog-cli-Binärprogramm ist eine vollständige Projektressourcen-CLI, nicht nur ein Test-Runner. Es verfügt über Befehlsgruppen für die gesamte Designoberfläche: schema für Datenmodelle, endpoint für Operationen, folder für die Organisation, security-scheme für die Authentifizierung, plus import, export, mock und mehr.
Eine ehrliche Anmerkung vorweg: Apidog lintet Ihr OpenAPI nicht und erzwingt keinen Styleguide. Dafür ist es nicht gedacht. Wenn Sie Linting benötigen, behalten Sie Spectral oder vacuum dafür in Ihrer Pipeline. Apidog ist auch nicht Open Source; es ist ein kommerzielles Produkt mit einem kostenlosen Tarif. Was es Ihnen bietet, ist ein integriertes Projekt, sodass Sie die Designteile nicht selbst zusammenfügen müssen. Unsere Betrachtung zu Swagger-Alternativen für API-Design und -Tests behandelt, wo dieser Kompromiss sinnvoll ist.
Installieren und authentifizieren Sie sich zuerst (siehe den Installationsleitfaden für die Token-Einrichtung):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Jeder Befehl gibt strukturiertes JSON zurück, und die meisten Antworten enthalten einen agentHints.nextSteps-Block, der Ihnen (oder einem Agenten) mitteilt, was als Nächstes ausgeführt werden soll. Fügen Sie --help zu jedem Befehl hinzu, um dessen genaue Flags anzuzeigen.
Datenmodelle mit apidog schema definieren
Das Design beginnt mit Ihren Daten. Ein wiederverwendbares Order-Schema wird zur einzigen Quelle der Wahrheit, auf die Endpunkte verweisen – dieselbe Idee wie components/schemas in reinem OpenAPI, aber als Projektressource verwaltet.
apidog schema --help
apidog schema create --project <PROJECT_ID>
Da die Ausgabe JSON ist, können Sie sie durch jq leiten, um die ID des neuen Schemas zu erhalten und sie in den nächsten Befehl einzuspeisen. Wenn Sie bereits eine OpenAPI-Datei haben, importieren Sie diese, anstatt alles neu einzugeben:
apidog import --project <PROJECT_ID> --file openapi.yaml
apidog import akzeptiert OpenAPI 3.x-, Swagger 2.0-, Postman- und Apidog-Formate, sodass eine bestehende Definition in einem Schritt zu einem Live-Projekt wird.
Endpunkte mit apidog endpoint definieren
Wenn Modelle vorhanden sind, fügen Sie Operationen hinzu. Die endpoint-Gruppe erstellt und aktualisiert Endpunkte und verbindet sie mit den von Ihnen definierten Schemas und den Ordnern, die sie organisieren.
apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Das Auflisten von Endpunkten als JSON ist für sich allein nützlich. Sie können die Ausgabe über Branches hinweg vergleichen oder sie einem Skript zuführen, das überprüft, ob jeder Pfad die erwarteten Antworten enthält. Gruppieren Sie verwandte Endpunkte mit dem Befehl folder, damit das Projekt mit seinem Wachstum navigierbar bleibt.
Authentifizierung mit apidog security-scheme definieren
Authentifizierung ist Teil des Vertrags, nicht nur ein nachträglicher Gedanke. Die Gruppe security-scheme definiert, wie Clients authentifizieren: API-Schlüssel, Bearer-Tokens, OAuth 2.0 und so weiter. Dies entspricht components/securitySchemes in OpenAPI, sodass Import und Export sauber verlaufen.
apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Die einmalige Definition des Schemas auf Projektebene bedeutet, dass jeder Endpunkt darauf verweisen kann, anstatt dass jede Operation ihre eigene Authentifizierung neu deklariert. Das ist genau die Art von Konsistenz, über die ein Linter Sie sonst ärgern würde.
Ihre Schreibvorgänge mit apidog cli-schema validate validieren
Bevor Sie Änderungen festschreiben oder ein Projekt an CI übergeben, möchten Sie wissen, dass Ihre Ressourcendefinitionen wohlgeformt sind. Die CLI liefert einen Befehl cli-schema validate, der eine Definitionsdatei gegen das Schema prüft, das die CLI erwartet, sodass ein fehlerhafter Schreibvorgang schnell fehlschlägt, anstatt stillschweigend zu landen.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
Führen Sie dies als Schutzschritt in Ihrer Pipeline aus: zuerst validieren, dann anwenden. Ein Exit-Code ungleich Null stoppt die Pipeline, bevor eine fehlerhafte Ressource das Projekt erreicht. Dies ist die Validierung Ihrer CLI-Schreibvorgänge, nicht das Linting des OpenAPI-Stils; das sind zwei verschiedene Aufgaben, und für die zweite möchten Sie immer noch Spectral verwenden.
Zurück nach OpenAPI exportieren
Entwerfen Sie in Apidog und übergeben Sie dann ein Standardartefakt an den Rest Ihrer Toolchain. apidog export schreibt OpenAPI, HTML, Markdown oder Postman.
apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
Jetzt haben Sie wieder eine portable OpenAPI-Datei. Führen Sie sie Spectral zum Linting, openapi-generator für Stubs oder Ihrem Dokumentations-Build zu. Das integrierte Projekt und der Open-Tool-Stack schließen sich nicht gegenseitig aus; der Export ist die Brücke zwischen ihnen.
In CI integrieren
Beide Wege glänzen in einer Pipeline, da jeder Befehl einen Exit-Code und eine Textausgabe hat. Ein minimaler Design-Check-Job könnte den Linter ausführen, dann validieren, dann bündeln:
# fail on style violations
spectral lint openapi.yaml
# validate any CLI resource writes before applying
apidog cli-schema validate --file resource.json
# flatten to a single artifact for downstream steps
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Da Apidogs Ausgabe JSON mit agentHints.nextSteps ist, kann dieser Workflow auch sauber von einem KI-Code-Agenten gesteuert werden. Der Agent liest das strukturierte Ergebnis, sieht den vorgeschlagenen nächsten Schritt und führt ihn aus, ohne ein GUI zu screen-scrapen. Das ist der Hauptgrund, überhaupt von der CLI aus zu entwerfen: Was ein Mensch eingibt, kann auch ein Skript oder ein Agent eingeben.
Häufige Fallstricke
Aufgeteilte Dateien stören nachgelagerte Tools. Eine Definition, die über viele $ref-Dateien verteilt ist, ist großartig für Menschen, aber umständlich für Generatoren. Bündeln Sie immer zu einer einzigen Datei, bevor Sie Code generieren oder Dokumente veröffentlichen. redocly bundle ist die Lösung.
Sie erwarten, dass Apidog lintet. Das tut es nicht. Apidog verwaltet Ressourcen; es erzwingt keinen Styleguide und kennzeichnet keine OpenAPI-Regelverletzungen. Halten Sie Spectral oder vacuum dafür in der Schleife. apidog cli-schema validate als Linter zu behandeln, ist die häufige Verwechslung; es validiert die Ressourcenstruktur, nicht den OpenAPI-Stil.
Vergessen, vor dem Bearbeiten zu importieren. Wenn Sie eine bestehende API über die CLI bearbeiten, importieren Sie zuerst die Quelldefinition in das Projekt. Ein leeres Projekt zu bearbeiten und zu erwarten, dass Ihre alten Endpunkte dort sind, führt schnell zu Verwirrung.
Authentifizierung pro Endpunkt statt einmalig definiert. Definieren Sie ein security-scheme auf Projektebene und referenzieren Sie es. Das Neudeklarieren der Authentifizierung bei jeder Operation führt dazu, dass Verträge abweichen.
Fazit
APIs über die CLI zu entwerfen, verwandelt eine klickintensive Aufgabe in eine Reihe wiederholbarer Befehle. Der offene Weg – erstellen, mit Spectral linten, mit Redocly bündeln, mit openapi-generator generieren – gibt Ihnen volle Kontrolle und keine Anbieterbindung. Der Apidog CLI-Weg bietet Ihnen ein integriertes Projekt, in dem Schemas, Endpunkte und Authentifizierung zusammenleben und jeder Befehl agenten-fertiges JSON zurückgibt. Der Export überbrückt die beiden, sodass Sie nie feststecken.
Wählen Sie den Weg, der zu Ihrem Team passt. Wenn Sie bereits mit einer Reihe spezialisierter Tools in Git arbeiten, behalten Sie diese bei und fügen Sie apidog export hinzu, wenn Sie ein portables Artefakt wünschen. Wenn Sie es vorziehen, die Verknüpfungsarbeit nicht selbst zu pflegen, laden Sie Apidog herunter, installieren Sie die CLI und entwerfen Sie Ihre nächste API, ohne eine Maus zu berühren.