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, die Header, der Authentifizierungstoken, der Abfrage-String, alles verdrahtet in einem requests-Aufruf oder einem fetch. Kopieren Sie ein Zeichen falsch, und Sie verbringen zwanzig Minuten damit, sich zu fragen, warum der Server einen 401 zurückgibt.

Sie müssen diesen Boilerplate-Code nicht von Hand schreiben. Wenn Ihre API in Apidog entworfen wurde, liest die Plattform Ihre Endpunkt-Spezifikation und liefert Ihnen ein sofort einfügbares Anforderungs-Snippet in der Sprache, in der Sie arbeiten: cURL für einen schnellen Terminal-Check, Python requests für ein Skript, JavaScript fetch oder Axios für ein Frontend. Dieser Leitfaden führt Sie durch die Generierung dieses Codes von einem realen Endpunkt, wann die Anforderung zuerst gesendet werden sollte, damit das Snippet tatsächliche Werte enthält, und wie der generierte Code bei Änderungen Ihrer Spezifikation genau bleibt. Wenn Sie einen breiteren Überblick über die Optionen wünschen, bietet Ihnen unsere Zusammenfassung der API-Code-Generierungstools die umfassendere Ansicht; hier bleiben wir praktisch mit dem integrierten Generator.

App herunterladen

Die Idee basiert darauf, dass eine Spezifikation die einzige Quelle der Wahrheit ist, dasselbe Prinzip, das hinter der OpenAPI Spezifikation steht. Wenn Sie die Definition einmal richtig haben, folgt der Anforderungscode daraus.

Was der Client-Code-Generator tatsächlich tut

Apidog verwandelt eine Endpunktdefinition in ein Anforderungs-Snippet pro Sprachvariante. Zeigen Sie auf GET /orders, wählen Sie Python und die Requests-Bibliothek, und es schreibt den Aufruf, der diesen Pfad mit den Headern und Parametern, die Ihre Spezifikation deklariert, anspricht. Es ist ein Anforderungsgenerator: Er produziert den Code für einen Aufruf, in der Syntax Ihrer gewählten Sprache und HTTP-Bibliothek.

Setzen Sie die Erwartungen an einem Punkt richtig. Diese Funktion generiert den Anforderungs- oder Client-Code für einen Endpunkt, nicht ein vollständiges SDK oder ein versioniertes Client-Bibliothekspaket. Wenn Sie eine cURL-Zeile, einen Python requests-Block oder ein JS fetch-Snippet benötigen, um es in Ihren Code einzufügen, dann ist es das, was Sie erhalten. Die Dokumentation beschreibt keinen vollständigen Bibliotheksgenerator, erwarten Sie also kein herunterladbares typisiertes SDK mit integrierten Modellen und Paginierungshilfen.

Dies passt natürlich zu einem Design-First-API-Entwicklungs-Workflow. Sie definieren den Vertrag, generieren den Anforderungscode direkt daraus, und jeder Konsument beginnt mit derselben genauen Definition anstatt mit einem in Slack eingefügten Screenshot.

Zwei Möglichkeiten, den Generator zu öffnen

Apidog bietet Ihnen zwei Einstiegspunkte für dieselbe Funktion. Verwenden Sie denjenigen, der am besten zu Ihrem aktuellen Standort passt.

Der erste Weg führt über die Dokumentation. Öffnen Sie den Dokumentations-Tab für Ihre API und klicken Sie dann auf die Schaltfläche Client-Code generieren auf der rechten Seite. Dies ist der schnellste Weg, wenn Sie die Dokumentation eines Endpunkts lesen und den entsprechenden Aufruf dazu benötigen.

Der zweite Weg führt über den Runner. Klicken Sie im Ausführen-Tab der API auf das Code-Symbol </>. Dies befindet sich neben der Stelle, an der Sie Anforderungen erstellen und senden, daher ist es die natürliche Wahl, wenn Sie den Aufruf bereits testen.

Beide öffnen dasselbe Panel. Von dort aus wählen Sie eine Sprache und eine Variante, und Apidog schreibt das Snippet.

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

Hier ist der vollständige Ablauf mit einem realistischen Endpunkt: ein GET /orders-Aufruf, der die Bestellungen eines Kunden auflistet, gefiltert nach Status und paginiert.

Schritt 1: Endpunkt öffnen und Sprache auswählen

Öffnen Sie den Dokumentations-Tab für den Endpunkt und klicken Sie auf Client-Code generieren. Wählen Sie im Panel Ihr Ziel. Apidog unterstützt eine lange Liste von Sprachen und Varianten, sodass Sie Ihren Stack genau anpassen können:

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
Andere: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, plus eine Option für rohes HTTP

Für dieses Beispiel wählen Sie Python und die Variante Requests. Apidog generiert aus der Spezifikation etwas Ähnliches wie dies:

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())

Kopieren Sie es, fügen Sie es in Ihr Skript ein, und es ist ein funktionierender Aufruf. Das ist der Design-First-Ansatz: Das Snippet spiegelt genau das wider, was Ihr Endpunkt deklariert.

Schritt 2: Wissen, was das reine Spezifikations-Snippet enthält

Es gibt einen Haken, den Sie verstehen sollten, bevor Sie den Code einfügen. Code, der direkt aus der API-Spezifikation generiert wird, enthält nur die API-Spezifikation, nicht aber reale Anforderungsparameterwerte oder Ihr Authentifizierungstoken. Sie erhalten die Form des Aufrufs und alle in der Spezifikation definierten Beispielwerte, aber nicht den aktiven Authorization: Bearer ...-Header, den Sie benötigen, um einen geschützten Endpunkt tatsächlich zu erreichen.

Das ist in Ordnung für einen Aufruf ohne Authentifizierung oder wenn Sie den Token selbst eingeben möchten. Für einen geschützten GET /orders möchten Sie die realen Werte im Code haben.

Schritt 3: Zuerst die Anforderung senden, um reale Werte zu erfassen

Um ein Snippet zu erhalten, das tatsächliche Parameterwerte und Authentifizierungsinformationen enthält, senden Sie zuerst die Anforderung und lesen Sie dann den Code aus dem Tab Tatsächliche Anforderung.

Wenn Sie design-first arbeiten, ist dies einfach. Definieren Sie den Endpunkt im Bearbeiten-Tab, klicken Sie auf den Ausführen-Tab, und die Anforderungsparameter werden automatisch aus der Spezifikation gefüllt. Wenn Sie die Dinge lieber manuell einrichten möchten (Request-First-Modus), geben Sie die Anforderungsparameter stattdessen manuell im Ausführen-Tab ein. In jedem Fall fügen Sie Ihr Authentifizierungstoken hinzu und klicken dann auf Senden, um die Anforderung zu übertragen.

Sobald die Antwort zurückkommt, wechseln Sie zum Tatsächliche Anforderung-Tab und scrollen Sie nach unten, um den Client-Code zu finden. Nun enthält das generierte Snippet die konkreten Werte und den Authentifizierungsheader, die tatsächlich gesendet 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())

Das ist der Unterschied zwischen den beiden Wegen. Der Design-First-Modus füllt Parameter automatisch aus der Spezifikation; der Request-First-Modus lässt Sie diese eingeben. Beide füllen dasselbe Tatsächliche Anforderung-Snippet, sobald Sie auf Senden klicken. Behandeln Sie einen echten Token wie den oben genannten als Geheimnis und halten Sie ihn von allem fern, was Sie an Git committet; die gleiche Sorgfalt, die Stripes Dokumentation für Live-Schlüssel empfiehlt, gilt auch hier.

Behandlung von Anforderungs-Bodies für POST und PUT

GET /orders hat keinen Body, aber sobald Sie Code für ein POST /orders oder ein PUT /orders/{id} generieren, benötigen Sie einen Request Body im Snippet. Apidog hilft Ihnen, diesen im Ausführen-Tab zu erstellen, bevor Sie generieren.

Für JSON- oder XML-Bodies haben Sie zwei Quellen. Verwenden Sie ein vordefiniertes Beispiel aus der Endpunktspezifikation oder klicken Sie auf Automatisch generieren, um eine Body-Struktur zu erstellen, die Ihrem Schema entspricht. Das Dropdown-Menü Automatisch generieren bietet Ihnen zwei Modi:

Beispiele: manuell ein vordefiniertes Anforderungs-Body-Beispiel auswählen.
Jedes Mal generieren: die Daten bei jeder Verwendung neu generieren, den intelligenten Mock-Regeln folgend, sodass Sie jedes Mal frische, schema-gültige Werte erhalten.

Sie können steuern, wie die Daten produziert werden, über die Unteroptionen der Automatischen Generierungseinstellungen: Zuerst Beispielwerte verwenden, Zuerst Standardwerte verwenden, Mock-Wert verwenden, Nur Feldnamen generieren und Anforderungsbeispiel verwenden. Wählen Sie Zuerst Beispielwerte verwenden, wenn Ihre Spezifikation gute Beispiele enthält und Sie diese berücksichtigen möchten; wählen Sie Mock-Wert verwenden, wenn Sie realistische generierte Daten für jedes Feld wünschen.

Ein Versionshinweis: Die Automatisch generieren-Optionen für Anforderungs-Bodies erfordern Apidog 2.7.0 oder höher. Wenn Sie sie nicht sehen, aktualisieren Sie die App. Ein gut spezifiziertes Schema mit Beispielen, wie es durch automatische Generierung von API-Dokumentation aus OpenAPI erhalten wird, führt dazu, dass dieser Schritt saubere Bodies mit fast keiner manuellen Bearbeitung erzeugt.

Wenn Sie einen Wert benötigen, der sich pro Anforderung ändert, wie einen neuen Zeitstempel oder eine zufällige Bestell-ID, fügen Sie einen dynamischen Wert ein, anstatt einen fest zu codieren. Klicken Sie auf das Zauberstab-Symbol neben einem Parameter-Eingabefeld oder verwenden Sie die Schaltfläche Dynamischen Wert einfügen innerhalb eines JSON- oder XML-Anforderungs-Bodies. Nachdem der Body fertig ist, klicken Sie auf Senden und lesen dann das fertige Snippet wie zuvor aus dem Tatsächliche Anforderung-Tab.

Wann ein Anforderungs-Snippet gegenüber einem Business-Modell-Aufruf zu verwenden ist

Eine schnelle Einschätzung: Wie viel Code sollten Sie kopieren?

Greifen Sie zu einem einzelnen Anforderungs-Snippet (cURL, fetch, ein reiner requests.get-Aufruf), wenn Sie eine einmalige Aktion durchführen. Debuggen, warum ein Endpunkt einen 403 zurückgibt, einen reproduzierbaren Aufruf in einem Ticket teilen, einen schnellen Check im Terminal durchführen oder ein Beispiel in Ihre eigene Dokumentation einfügen. Es ist in sich geschlossen und benötigt keine umgebende Struktur.

Neigen Sie zu dem vollständigeren Code im Business-Modell-Stil (der Axios- oder requests-Block mit Headern, Parametern und Response-Behandlung), wenn der Aufruf innerhalb der realen Anwendungslogik liegt. Wenn GET /orders in einem Dienstmodul sitzen soll, das von drei Stellen aufgerufen wird, möchten Sie die strukturierte Version, die Sie in eine Funktion packen, Fehlerbehandlung hinzufügen und wiederverwenden können. Der Generator bietet Ihnen beide Formen, je nachdem, welche Variante Sie wählen; passen Sie die Form an den Ort an, an dem der Code leben wird.

Wenn Sie dieselben Endpunkte mit derselben Authentifizierung über ein ganzes Projekt hinweg aufrufen, ist es oft sauberer, die gemeinsamen Teile zu zentralisieren. Unser Leitfaden zum Festlegen globaler Parameter in Apidog zeigt, wie Sie Header und Variablen einmal definieren können, sodass jeder generierte Aufruf sie erbt, anstatt den Token in jedem Snippet zu wiederholen.

Generierten Code durch die Spec-First-Gewohnheit genau halten

Generierter Code ist nur so korrekt wie die Spezifikation, die dahinter steckt. Ändern Sie GET /orders, um einen region-Abfrageparameter hinzuzufügen, und vergessen Sie, neu zu generieren, und Ihr kopiertes Snippet ist stillschweigend falsch. Die Lösung besteht darin, die Spezifikation als das zu behandeln, was Sie pflegen, und den Code als eine abgeleitete Ausgabe, die Sie bei Bedarf neu generieren. Apidogs Spec-First-Modus hält die Definition maßgeblich, sodass der von Ihnen generierte Anforderungscode immer den aktuellen Vertrag widerspiegelt und nicht einen veralteten.

Für die Syntax der Snippets selbst ist die MDN-Dokumentation zur Fetch API eine solide Referenz, wenn Sie die von Apidog produzierten JavaScript-Varianten verstehen oder anpassen möchten.

Den Workflow mit der Apidog CLI automatisieren

Die Code-Generierung selbst ist eine GUI-Aktion; Sie kopieren ein Snippet aus einem Panel, und es gibt keinen separaten CLI-Befehl, der Client-Code ausgibt. Was die Apidog CLI gut kann, ist, die beiden Dinge zu pflegen, von denen die Generierung abhängt: eine aktuelle Spezifikation und erfolgreiche Tests, die beweisen, dass der generierte Client tatsächlich funktioniert.

Installieren Sie es mit npm install -g apidog-cli (Node.js v16+) und authentifizieren Sie sich:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Importieren Sie frische Spezifikationsänderungen, damit der von Ihnen generierte Code aktuell bleibt, und führen Sie das gespeicherte Testszenario aus, das den Endpunkt testet, den Ihr Client aufruft:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Hier ist -t die ID des Testszenarios, -e die ID der Umgebung und -r der Reporter (cli, html oder junit). Binden Sie dies in Ihre Pipeline ein, so wie es unser Leitfaden zu Apidog CLI GitHub Actions darlegt, und jeder Push überprüft, ob GET /orders sich immer noch wie in der Spezifikation versprochen verhält, bevor jemand einen Client daraus neu generiert. Die CLI schreibt Ihren Client-Code nicht, aber sie schützt den Vertrag, auf dem dieser Code basiert.

FAQ

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

Standardmäßig nicht. Code, der allein aus der API-Spezifikation generiert wird, enthält nur die Spezifikation, nicht aber reale Parameterwerte oder die Authentifizierung. Um ein Snippet mit Ihrem tatsächlichen Token und Werten zu erhalten, senden Sie zuerst die Anforderung und lesen Sie dann den Code aus dem Tab Tatsächliche Anforderung. Behandeln Sie jeden Token in diesem Snippet als Geheimnis.

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

Eine breite Palette. Shell (cURL, Httpie, wget, PowerShell), JavaScript (Fetch, Axios, jQuery, XHR und mehr), Python (http.client und Requests), Java (Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R und andere. Sie wählen die Sprache und die spezifische Variante im Generator-Panel.

Warum sehe ich die Optionen zum automatischen Generieren für Anforderungs-Bodies nicht?

Diese Optionen erfordern Apidog 2.7.0 oder höher. Aktualisieren Sie die App, und sie werden im Ausführen-Tab angezeigt, wenn Sie einen JSON- oder XML-Body erstellen. Sobald verfügbar, bietet das Dropdown-Menü Automatisch generieren die Optionen Beispiele und Jedes Mal generieren, mit bevorzugten Unteroptionen dafür, wie Werte erzeugt werden.

Ist die Client-Code-Generierung eine kostenpflichtige Funktion?

Die Apidog-Dokumentation zieht keine Grenze zwischen kostenlos und kostenpflichtig oder Cloud und selbst gehostet für die Generierung von Client-Code. Die einzige Versionsanforderung, die irgendwo erwähnt wird, ist, dass die Automatisch generieren-Optionen für Anforderungs-Bodies Version 2.7.0 oder höher benötigen. Sie können Apidog herunterladen und den Generator ohne kostenpflichtigen Plan ausprobieren.

Wie stelle ich sicher, dass der generierte Aufruf tatsächlich funktioniert?

Generieren Sie das Snippet und verifizieren Sie dann den Endpunkt mit einem gespeicherten Test. Unser Leitfaden zum Schreiben eines Testszenarios mit Apidog zeigt, wie man eines erstellt, und die CLI kann es in CI ausführen, sodass ein gebrochener Vertrag den Build fehlschlägt, bevor Sie einen Client daraus neu generieren.

Zusammenfassung

Die Generierung von Client-Code in Apidog verwandelt eine Endpunkt-Spezifikation in eine sofort einfügbare Anforderung in der Sprache, in der Sie arbeiten, und der Tatsächliche Anforderung-Tab ist der Trick, um echte Werte und Authentifizierung in dieses Snippet zu bekommen, anstatt einer leeren Vorlage. Halten Sie die Spezifikation maßgeblich, generieren Sie neu, wenn sie sich ändert, und lassen Sie einen gespeicherten Test bestätigen, dass der Aufruf immer noch funktioniert. Laden Sie Apidog herunter, um mitzumachen, definieren Sie Ihren GET /orders-Endpunkt und kopieren Sie mit wenigen Klicks einen funktionierenden Client-Aufruf.