DEV Community

Cover image for So generieren Sie Client-Code aus Ihrer API-Spezifikation in Apidog
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

So generieren Sie Client-Code aus Ihrer API-Spezifikation in Apidog

Sie haben einen Endpunkt definiert und möchten ihn von Ihrer App aus aufrufen. Der mühsame Teil ist die Übersetzung der Spezifikation in funktionierenden Code: die richtige URL, Header, Authentifizierungstoken und Query-Parameter – alles verdrahtet in einem requests-Aufruf oder fetch. Ein falsch kopiertes Zeichen genügt, und Sie verbringen zwanzig Minuten mit der Frage, warum der Server 401 zurückgibt.

Apidog noch heute ausprobieren

Sie müssen diesen Boilerplate-Code nicht manuell schreiben. Wenn Ihre API in Apidog entworfen wurde, liest die Plattform Ihre Endpunkt-Spezifikation und erzeugt sofort einfügbaren Anforderungscode für Ihren Stack: cURL für einen schnellen Terminal-Check, Python requests für Skripte sowie JavaScript fetch oder Axios für Frontends.

Dieser Leitfaden zeigt den praktischen Ablauf an einem Endpunkt, wann Sie eine Anfrage zuerst senden sollten, damit das Snippet reale Werte enthält, und wie Sie generierten Code bei Änderungen der Spezifikation aktuell halten. Für einen breiteren Überblick lesen Sie unsere Zusammenfassung der API-Code-Generierungstools.

Die Idee basiert darauf, dass eine Spezifikation die einzige Quelle der Wahrheit ist – dasselbe Prinzip, das hinter der OpenAPI-Spezifikation steht. Wenn die Definition korrekt ist, lässt sich der Anforderungscode daraus ableiten.

Was der Client-Code-Generator tatsächlich tut

Apidog wandelt eine Endpunktdefinition in ein Anforderungs-Snippet für die gewählte Sprache und Bibliothek um.

Wählen Sie beispielsweise GET /orders, Python und die Bibliothek Requests. Der Generator erstellt einen Aufruf mit:

  • dem definierten Pfad,
  • den deklarierten Headern,
  • Query-Parametern,
  • dem passenden HTTP-Verb,
  • der Syntax der ausgewählten Bibliothek.

Wichtig: Die Funktion generiert Code für eine konkrete HTTP-Anfrage, kein vollständiges SDK oder versioniertes Client-Bibliothekspaket.

Sie erhalten beispielsweise:

  • eine cURL-Zeile,
  • einen Python-requests-Block,
  • ein JavaScript-fetch-Snippet,
  • einen Axios-Aufruf.

Sie erhalten kein herunterladbares, typisiertes SDK mit Modellen, Paginierungshelfern oder einer vollständigen Client-Architektur.

Das passt gut zu einem Design-First-API-Entwicklungs-Workflow: Sie definieren den Vertrag, generieren den Anforderungscode daraus und stellen sicher, dass alle API-Konsumenten mit derselben Definition arbeiten.

Zwei Möglichkeiten, den Generator zu öffnen

Apidog bietet zwei Einstiegspunkte für dieselbe Funktion.

Über die Dokumentation

  1. Öffnen Sie den Tab Dokumentation Ihrer API.
  2. Wählen Sie den gewünschten Endpunkt.
  3. Klicken Sie rechts auf Client-Code generieren.
  4. Wählen Sie Sprache und Bibliotheksvariante.

Dieser Weg eignet sich, wenn Sie gerade die Endpunkt-Dokumentation lesen und schnell einen passenden Aufruf benötigen.

Über den Runner

  1. Öffnen Sie den Tab Ausführen.
  2. Konfigurieren oder testen Sie die Anfrage.
  3. Klicken Sie auf das Code-Symbol </>.

Dieser Weg ist sinnvoll, wenn Sie den Endpunkt bereits testen und Code mit den tatsächlich gesendeten Werten benötigen.

Beide Wege öffnen dasselbe Generator-Panel.

Einen Python-Client-Aufruf für GET /orders generieren

Nehmen wir einen realistischen Endpunkt:

GET /orders
Enter fullscreen mode Exit fullscreen mode

Der Endpunkt listet Bestellungen eines Kunden auf, gefiltert nach Status und paginiert.

Schritt 1: Endpunkt öffnen und Sprache auswählen

Öffnen Sie den Tab Dokumentation für den Endpunkt und klicken Sie auf Client-Code generieren.

Apidog unterstützt unter anderem diese Sprachen und Varianten:

  • Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
  • JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
  • Python: http.client, Requests
  • Java: Unirest, OkHttp
  • Go: Native
  • PHP: cURL, Guzzle, pecl_http, HTTP_Request2
  • Weitere: Swift mit URLSession, C mit libcurl, C#, Objective-C, Ruby, OCaml, Dart, R und rohes HTTP

Wählen Sie für dieses Beispiel Python und Requests. Aus der Spezifikation entsteht ein Snippet wie dieses:

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {"Accept": "application/json"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
Enter fullscreen mode Exit fullscreen mode

Kopieren Sie den Code in Ihr Skript und ergänzen Sie bei Bedarf Fehlerbehandlung, Timeouts und Ihre Anwendungslogik.

Schritt 2: Verstehen, was ein Spezifikations-Snippet enthält

Code, der direkt aus der API-Spezifikation erzeugt wird, enthält:

  • die URL und HTTP-Methode,
  • deklarierte Header,
  • definierte Parameter,
  • Beispielwerte aus der Spezifikation.

Er enthält in der Regel keine realen Laufzeitwerte und keinen aktiven Authentifizierungstoken.

Ein geschützter Endpunkt benötigt jedoch häufig einen Header wie:

Authorization: Bearer <token>
Enter fullscreen mode Exit fullscreen mode

Wenn Sie nur die Struktur des Aufrufs brauchen, reicht das Spezifikations-Snippet aus. Wenn Sie einen direkt ausführbaren Aufruf mit Ihren aktuellen Parametern und Authentifizierungsdaten benötigen, sollten Sie die Anfrage zuerst senden.

Schritt 3: Anfrage senden und reale Werte übernehmen

Um ein Snippet mit tatsächlich verwendeten Parametern und Authentifizierungsinformationen zu erhalten:

  1. Öffnen Sie den Tab Ausführen.
  2. Prüfen oder ergänzen Sie Query-Parameter und Header.
  3. Fügen Sie Ihren Authentifizierungstoken hinzu.
  4. Klicken Sie auf Senden.
  5. Wechseln Sie nach der Antwort in den Tab Tatsächliche Anforderung.
  6. Scrollen Sie zum Bereich mit dem Client-Code.

Das erzeugte Snippet enthält nun die Werte, die tatsächlich übertragen wurden:

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer sk_live_51H8xY2..."
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
Enter fullscreen mode Exit fullscreen mode

Im Design-First-Modus werden Parameter aus der Spezifikation automatisch befüllt. Im Request-First-Modus geben Sie die Werte manuell im Tab Ausführen ein. Nach dem Senden erhalten Sie in beiden Fällen ein Snippet aus der Tatsächlichen Anforderung.

Behandeln Sie Tokens immer als Geheimnisse:

  • Committen Sie sie nicht in Git.
  • Speichern Sie sie nicht direkt im Quellcode.
  • Verwenden Sie Umgebungsvariablen oder einen Secret-Manager.

Die Empfehlungen aus der Stripe-Dokumentation zu Live-Schlüsseln gelten ebenso für API-Tokens in generierten Snippets.

Request Bodies für POST und PUT behandeln

GET /orders benötigt keinen Request Body. Für Endpunkte wie diese schon:

POST /orders
PUT /orders/{id}
Enter fullscreen mode Exit fullscreen mode

Erstellen Sie den Body im Tab Ausführen, bevor Sie den Code generieren.

Für JSON- und XML-Bodies gibt es zwei Quellen:

  1. Ein vordefiniertes Beispiel aus der Endpunktspezifikation verwenden.
  2. Auf Automatisch generieren klicken, um eine Struktur aus dem Schema zu erzeugen.

Das Menü Automatisch generieren bietet zwei Modi:

  • Beispiele: Wählen Sie ein vorhandenes Request-Body-Beispiel.
  • Jedes Mal generieren: Erzeugen Sie bei jeder Verwendung neue, schema-gültige Werte anhand intelligenter Mock-Regeln.

Über die Automatischen Generierungseinstellungen steuern Sie die Priorität der Werte:

  • Zuerst Beispielwerte verwenden
  • Zuerst Standardwerte verwenden
  • Mock-Wert verwenden
  • Nur Feldnamen generieren
  • Anforderungsbeispiel verwenden

Praktische Auswahl:

  • Verwenden Sie Zuerst Beispielwerte verwenden, wenn Ihre OpenAPI-Spezifikation gute Beispiele enthält.
  • Verwenden Sie Mock-Wert verwenden, wenn Sie für jedes Feld realistisch wirkende Testdaten benötigen.

Die Optionen für automatisch generierte Request Bodies benötigen Apidog 2.7.0 oder höher. Wenn die Optionen fehlen, aktualisieren Sie die App.

Ein gut beschriebenes Schema mit Beispielen verbessert die generierten Bodies deutlich. Informationen dazu finden Sie auch im Beitrag zur automatischen Generierung von API-Dokumentation aus OpenAPI.

Für Werte, die sich bei jeder Anfrage ändern sollen, verwenden Sie dynamische Werte statt fest codierter Daten. Beispiele:

  • Zeitstempel
  • zufällige Bestell-ID
  • zufällige E-Mail-Adresse
  • generierte UUID

Klicken Sie auf das Zauberstab-Symbol neben einem Parameterfeld oder auf Dynamischen Wert einfügen innerhalb eines JSON- oder XML-Bodies.

Senden Sie anschließend die Anfrage und kopieren Sie den fertigen Code aus dem Tab Tatsächliche Anforderung.

Wann Sie ein Anforderungs-Snippet verwenden sollten

Ein einzelnes Anforderungs-Snippet – etwa cURL, fetch oder requests.get – eignet sich für isolierte Aufgaben:

  • Einen 403 oder 401 debuggen
  • Einen reproduzierbaren Aufruf in einem Ticket teilen
  • Einen schnellen Terminal-Check durchführen
  • Ein Beispiel in interne Dokumentation übernehmen
  • Einen Endpunkt unabhängig von Ihrer Anwendung testen

Beispiel mit cURL:

curl --request GET \
  --url "https://api.example.com/orders?status=shipped&page=1" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $API_TOKEN"
Enter fullscreen mode Exit fullscreen mode

Für produktive Anwendungslogik sollten Sie den generierten Code in eine wiederverwendbare Struktur überführen:

import os
import requests

API_BASE_URL = "https://api.example.com"
API_TOKEN = os.environ["API_TOKEN"]

def get_orders(status: str, page: int = 1) -> dict:
    response = requests.get(
        f"{API_BASE_URL}/orders",
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {API_TOKEN}",
        },
        params={
            "status": status,
            "page": page,
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()
Enter fullscreen mode Exit fullscreen mode

Wenn mehrere Endpunkte dieselben Header, Variablen oder Authentifizierungsdaten verwenden, zentralisieren Sie diese Konfiguration. Der Leitfaden zum Festlegen globaler Parameter in Apidog zeigt, wie Sie gemeinsame Werte einmal definieren, statt sie in jedem Snippet zu wiederholen.

Generierten Code mit einer Spec-First-Gewohnheit aktuell halten

Generierter Code ist nur so korrekt wie die Spezifikation, aus der er abgeleitet wurde.

Beispiel: Sie ergänzen für GET /orders einen neuen Query-Parameter:

region=eu
Enter fullscreen mode Exit fullscreen mode

Wenn Sie den Endpunkt aktualisieren, aber ein zuvor kopiertes Snippet weiterverwenden, fehlt der neue Parameter möglicherweise. Der Code ist dann stillschweigend veraltet.

Behandeln Sie deshalb:

  • die Spezifikation als gepflegte Quelle der Wahrheit,
  • generierten Code als abgeleitete Ausgabe,
  • Snippets als Artefakte, die Sie bei Änderungen neu erzeugen.

Der Spec-First-Modus von Apidog hilft dabei, die Definition maßgeblich zu halten. Neu generierter Anforderungscode spiegelt dann den aktuellen API-Vertrag wider.

Wenn Sie JavaScript-Snippets mit fetch anpassen möchten, ist die MDN-Dokumentation zur Fetch API eine zuverlässige Referenz.

Den Workflow mit der Apidog CLI automatisieren

Die Client-Code-Generierung selbst erfolgt in der GUI: Sie öffnen das Generator-Panel und kopieren das Snippet.

Die Apidog CLI hilft jedoch bei den Grundlagen, von denen zuverlässiger generierter Code abhängt:

  • eine aktuelle Spezifikation,
  • automatisierte Tests,
  • reproduzierbare Validierung in CI.

Installieren Sie die CLI mit Node.js 16 oder höher:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Authentifizieren Sie sich anschließend:

apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Führen Sie ein gespeichertes Testszenario für den Endpunkt aus:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Die Optionen bedeuten:

  • -t: ID des Testszenarios
  • -e: ID der Umgebung
  • -r: Reporter, etwa cli, html oder junit

Binden Sie den Befehl in Ihre Pipeline ein. Der Leitfaden zu Apidog CLI GitHub Actions zeigt den Ablauf.

Die CLI schreibt keinen Client-Code. Sie prüft jedoch, ob der API-Vertrag weiterhin funktioniert, bevor jemand neue Snippets aus der Spezifikation generiert.

FAQ

Enthält der generierte Code meinen API-Schlüssel oder Token?

Standardmäßig nicht. Code aus der API-Spezifikation enthält die Struktur der Anfrage, aber keine realen Laufzeitwerte oder Authentifizierungsdaten. Senden Sie die Anfrage zuerst und kopieren Sie anschließend den Code aus dem Tab Tatsächliche Anforderung, wenn Sie aktuelle Werte benötigen. Behandeln Sie enthaltene Tokens als Geheimnisse.

Für welche Sprachen und Bibliotheken kann Apidog Code generieren?

Apidog unterstützt unter anderem Shell, JavaScript, Python, Java, Go, PHP, Swift, C, C#, Ruby, Dart und R. Verfügbare Varianten umfassen beispielsweise cURL, Fetch, Axios, Requests, OkHttp und Unirest.

Warum sehe ich keine Optionen zum automatischen Generieren von Request Bodies?

Diese Optionen benötigen Apidog 2.7.0 oder höher. Aktualisieren Sie die App und öffnen Sie einen Endpunkt mit JSON- oder XML-Body im Tab Ausführen.

Ist die Client-Code-Generierung eine kostenpflichtige Funktion?

Die Apidog-Dokumentation unterscheidet für die Client-Code-Generierung nicht zwischen kostenlos und kostenpflichtig oder zwischen Cloud und Self-Hosting. Die erwähnte Versionsanforderung betrifft die Optionen zum automatischen Generieren von Request Bodies ab Version 2.7.0. Sie können Apidog herunterladen und den Generator ausprobieren.

Wie prüfe ich, ob der generierte Aufruf wirklich funktioniert?

Generieren Sie das Snippet und testen Sie den Endpunkt mit einem gespeicherten Testszenario. Der Leitfaden zum Schreiben eines Testszenarios mit Apidog beschreibt die Einrichtung. Führen Sie das Szenario anschließend mit der CLI in CI aus, damit ein gebrochener Vertrag den Build fehlschlagen lässt.

Zusammenfassung

Die Client-Code-Generierung in Apidog übersetzt eine Endpunkt-Spezifikation in direkt nutzbare HTTP-Anfragen für Ihre Sprache und Bibliothek.

Der praktische Ablauf ist:

  1. Endpunkt in Dokumentation oder Runner öffnen.
  2. Sprache und Bibliothek auswählen.
  3. Für reale Parameter und Authentifizierung die Anfrage zuerst senden.
  4. Code aus dem Tab Tatsächliche Anforderung kopieren.
  5. Secrets aus dem Snippet entfernen oder durch Umgebungsvariablen ersetzen.
  6. Bei jeder Spezifikationsänderung neu generieren.
  7. Den API-Vertrag mit gespeicherten Tests und CLI-Ausführung absichern.

Laden Sie Apidog herunter, definieren Sie Ihren GET /orders-Endpunkt und erzeugen Sie mit wenigen Klicks einen passenden Client-Aufruf.

Top comments (0)