Wenn Sie ein Online-API-Dokument öffnen, das mit Apidog veröffentlicht wurde, werden Sie neben jedem Endpunkt eine Schaltfläche "Try it" bemerken. Wenn Sie darauf klicken, wird ein Debug-Panel auf der rechten Seite der Seite eingeblendet, das es Ihnen ermöglicht, die API direkt innerhalb der Dokumentation zu testen.
Die Benutzerfreundlichkeit dieser "Debug"-Funktion hängt jedoch maßgeblich davon ab, wie gut Sie sie innerhalb der Plattform konfiguriert haben. Faktoren wie eine korrekte URL-Einrichtung, Authentifizierungskonfiguration, eine klare Parameterstruktur und vollständige Beispieldaten beeinflussen das Debugging-Erlebnis erheblich.
Wenn nicht richtig konfiguriert, können Benutzer viel Zeit mit dem Ausfüllen von Parametern verbringen oder sogar keine erfolgreichen API-Aufrufe tätigen, was alles andere als ideal ist.
Lassen Sie uns besprechen, wie Apidog effektiv konfiguriert werden kann, um sicherzustellen, dass die veröffentlichte Online-Dokumentation ein exzellentes Debugging-Erlebnis bietet.
Korrekte URL-Konfiguration
Oft sieht die Online-Dokumentation gut aus, schlägt aber fehl, wenn Sie auf die Schaltfläche "Try it" klicken, um eine Anfrage zu senden. Der häufigste Grund ist, dass der Endpunkt nur einen Pfad wie /pet/{petId} enthält, ohne dass bei der Veröffentlichung eine Laufzeitumgebung ausgewählt wurde.
Dies führt zu unvollständigen Anforderungs-URLs ohne Protokoll oder Hostname, was beim Senden von Anfragen zu Fehlern führt.
Um dies zu beheben, stellen Sie sicher, dass Benutzer auf die korrekte URL zugreifen können. Apidog bietet drei Möglichkeiten, URLs für die Online-Dokumentation zu konfigurieren, je nach Ihren Anforderungen.
1. Basis-URLs verwenden
Dies ist der empfohlene Ansatz. Definieren Sie nur den Pfad im Endpunkt, z. B. /pet/{petId}, und konfigurieren Sie die vollständige Dienstadresse (z. B. https://product.example.com) im Abschnitt "Environment Management" als Basis-URL.
Beim Veröffentlichen der API-Dokumentation wählen Sie die entsprechende Laufzeitumgebung aus. Apidog verkettet die Basis-URL automatisch mit dem Endpunktpfad. Sie können auch mehrere Laufzeitumgebungen definieren, jede mit ihrer eigenen Basis-URL.
In der Online-Dokumentation können Benutzer schnell Umgebungen aus einer Dropdown-Liste wechseln, und alle Endpunkt-URLs werden entsprechend aktualisiert. Dies macht es bequem, APIs in verschiedenen Umgebungen zu validieren.
Hinweis: Beachten Sie Protokollprobleme. Viele Browser schränken HTTPS-Seiten daran ein, HTTP-APIs aufzurufen. Wenn Ihre API HTTP verwendet, können Benutzer beim Debuggen auf einer HTTPS-Dokumentationsseite auf Cross-Protokoll-Probleme stoßen.
2. Vollständige URLs in Endpunkten einfügen
Eine weitere Option ist, die vollständige URL direkt im Endpunkt anzugeben, z. B. https://product.example.com/pet/{petId}.
Dies stellt sicher, dass die vollständige Anforderungs-URL unabhängig von der ausgewählten Laufzeitumgebung sichtbar ist. Die Verwaltung von Änderungen an Serveradressen wird jedoch umständlich, da Sie jeden Endpunkt einzeln aktualisieren müssen. Daher ist diese Methode weniger empfehlenswert.
3. Variablen in URLs verwenden
Wenn Sie möchten, dass Benutzer die URL für das Debugging anpassen können, können Sie Variablen verwenden. Erstellen Sie beispielsweise eine Umgebungsvariable BaseURL im Abschnitt "Environment Management" und referenzieren Sie diese in der Basis-URL als {{BaseURL}}.
In der Online-Dokumentation können Benutzer auf den Variablennamen klicken und diesen zu ihrer gewünschten URL ändern.
Alternativ können Sie Variablen direkt im Endpunkt definieren, z. B. {{BaseURL}}/pet/{petId}.
Für diesen spezifischen Endpunkt in der Online-Dokumentation können Benutzer den Wert der Variable festlegen, um die Anfrage zu senden.
Bevor Sie die Dokumentation veröffentlichen, stellen Sie sicher, dass die "initial values" in der Umgebung keine sensiblen Informationen (z. B. Authentifizierungsdaten) enthalten, da diese Werte in der veröffentlichten Dokumentation enthalten sein werden und Datenschutzrisiken darstellen können.
Korrekte Authentifizierungskonfiguration
Basic Auth Einrichtung
Erfolgreiche Endpunktanfragen erfordern oft eine Authentifizierung. Apidog unterstützt verschiedene Authentifizierungstypen, darunter Bearer Token, API Key, OAuth2.0 und Basic Auth.
Sie können die Authentifizierung auf Endpunkt- oder Ordnerebene mithilfe eines Sicherheitsschemas oder durch manuelle Einstellung konfigurieren.
Wenn Sie beispielsweise Bearer Token als Authentifizierungstyp verwenden, erscheint oben im Debug-Panel der Online-Dokumentation ein "Token"-Feld. Benutzer können den Token-Wert direkt eingeben, ohne das Präfix "Bearer" manuell hinzuzufügen. Apidog erledigt dies automatisch, was bequemer ist als das manuelle Hinzufügen eines Autorisierungs-Headers.
Der Vorteil dieser Einrichtung ist, dass Authentifizierungsinformationen über mehrere Endpunkte hinweg geteilt werden können. Wenn mehrere Endpunkte dasselbe Sicherheitsschema oder denselben Typ verwenden, müssen Sie die Anmeldeinformationen nur einmal eingeben. Jegliche Aktualisierungen der Anmeldeinformationen werden automatisch auf alle zugehörigen Endpunkte angewendet.
Authentifizierungsdaten werden verschlüsselt und lokal im Browser des Benutzers gespeichert, pro Sitzung verwaltet und über Tabs und Fenster hinweg geteilt. Sie werden gelöscht, wenn der Browser geschlossen wird, was das Risiko der Offenlegung sensibler Informationen in veröffentlichten Dokumentationen reduziert.
OAuth2.0 Konfiguration
Für die OAuth2.0-Authentifizierung, wenn Sie möchten, dass Benutzer Token direkt während des Debuggings generieren, konfigurieren Sie die Details des Autorisierungsservers (z. B. Auth URL, Token URL) im Projekt.
Bei Verwendung des OAuth2.0-Sicherheitsschemas müssen Benutzer während des Debuggings die Client-ID, das Client-Secret usw. eingeben. Ein Pop-up führt sie durch den Autorisierungsprozess, und der erhaltene access_token wird automatisch auf nachfolgende API-Anfragen angewendet.
Klare Parameterstrukturen entwerfen
Parameteranzeige im Debug-Panel
Das Debug-Panel zeigt Parameterabschnitte intelligent basierend auf Ihrem Endpunkt-Design an. Wenn der Endpunkt beispielsweise nur Pfadparameter definiert, zeigt das Debug-Panel nur den Pfadabschnitt an, wodurch unnötige Abfrage- oder Body-Abschnitte vermieden werden.
Diese Klarheit hilft Benutzern zu verstehen, welche Parameter ausgefüllt werden müssen, ohne durch irrelevante Abschnitte abgelenkt zu werden.
Beispiel bereitstellen
Beim Entwerfen von Endpunkten definieren Sie den Typ und die erforderlichen Attribute jedes Parameters genau. Fügen Sie klare Beschreibungen und Beispiele hinzu, da diese im Debug-Panel vorausgefüllt werden, was die Benutzerfreundlichkeit verbessert.
Redundante Header vermeiden
Wenn der Endpunkt Body-Parameter definiert, ist es nicht notwendig, Header wie Content-Type: application/json manuell hinzuzufügen. Apidog verarbeitet solche Header während der Anfragen automatisch.
Ähnlich verhält es sich, wenn die Authentifizierung konfiguriert ist: Vermeiden Sie eine Duplizierung in den Headern. Authentifizierungseinstellungen haben Vorrang und überschreiben alle widersprüchlichen Header-Konfigurationen.
Umfassende Anfragebeispiele anbieten
Für Endpunkte mit komplexen JSON-Anfragekörpern stellen Sie beim Design mehrere Anfragekörper-Beispiele bereit.
Benutzer können diese Beispiele aus einem Dropdown-Menü im Debug-Panel auswählen, was Zeit spart und Fehler reduziert.
Stellen Sie sicher, dass die Beispieldaten realen Szenarien ähneln, aber vermeiden Sie die Aufnahme sensibler Informationen. Benutzer können diese Beispiele nach Bedarf ändern.
Klare Antwortbeispiele konfigurieren
Nach dem Senden einer Anfrage zeigt das Debug-Panel die vollständige Antwort an, einschließlich Statuscodes, Headern und Body. Als Dokumentationsersteller konfigurieren Sie klare Antwortbeispiele, um Benutzern zu helfen, die möglichen Ergebnisse zu verstehen.
Stellen Sie mehrere Antwortbeispiele für jeden Endpunkt bereit, z. B. Erfolg (200), fehlerhafte Anfrage (400) und nicht autorisiert (401).
Achten Sie besonders auf Fehlerantworten und erklären Sie deutlich die Fehlercodes und Nachrichtenformate für verschiedene Szenarien. Dies hilft Benutzern, Probleme während des Debuggings schnell zu identifizieren und zu beheben.
Beispielcode für die Integration bereitstellen
Obwohl Apidog automatisch Beispielcode für gängige Programmiersprachen generiert, stimmt der generierte Code möglicherweise nicht vollständig mit Ihren Geschäftsanforderungen überein. In solchen Fällen passen Sie die Beispiele an.
Sie können konfigurieren, welche Sprachen automatisch generierte Beispiele benötigen, unter "Project Settings -> Endpoint Feature Settings -> Request Code Samples."
Zusätzlich können Sie benutzerdefinierten Beispielcode für bestimmte Endpunkte im Abschnitt "Endpoint Description" schreiben.
Dies stellt sicher, dass Benutzer sowohl automatisch generierte als auch benutzerdefinierte Beispiele in der Online-Dokumentation sehen, was die Integration erleichtert.
Zusammenfassung
Das Debugging-Erlebnis der Online-Dokumentation hängt stark von der korrekten Konfiguration ab. Durchdachte Einrichtung von URLs, Authentifizierung, Parameterstrukturen und Beispielen stellt sicher, dass Benutzer schnell mit Ihrer API beginnen können, ohne von technischen Details überfordert zu werden.