Try It! ist die interaktive API von Document360, die direkt in deine veröffentlichte API-Referenz eingebettet ist. Es ermöglicht Entwicklern, echte Anfragen an deine API-Endpunkte zu senden und Live-Antworten zu sehen, ohne die Dokumentation zu verlassen oder Code schreiben zu müssen.
Dieser Artikel erklärt, wie die Try It!-Konsole in deiner veröffentlichten API-Referenz funktioniert – wie man sie öffnet, eine Anfrage erstellt und sendet, die Antwort liest und was die Konsole unterstützt und was nicht. Details zur Konfiguration jeder Authentifizierungsmethode finden Sie unter Autorisierung von Anfragen in der Try It-Konsole.
Was Try It! tut
Von jeder Endpunktseite in Ihrer veröffentlichten API-Referenz aus können Entwickler:
- Öffne eine interaktive Konsole direkt am Endpunkt, ohne die Seite zu verlassen
- Füllen Sie Pfad- und Abfrageparameter, Header und (für Schreibmethoden) einen Request-Body aus
- Bereitstellung von Authentifizierungsdaten für das Sicherheitsschema des Endpunkts
- Senden Sie eine Live-Anfrage und sehen Sie sich die tatsächliche Antwort an – Status, Timing, Überschriften und Text
Try It! ist nicht für Webhooks verfügbar. Webhook-Seiten zeigen das Nutzlastschema und ein Beispiel, können aber keine Testanfragen senden.
Öffnen der Try It-Konsole
Auf jeder Endpunktseite erscheinen die Methode und die URL des Endpunkts oben, mit einem Try It-Button daneben.
- Klicke auf Try It. Die interaktive Konsole öffnet sich inline, direkt unter der Endpunkt-URL.
- Erstellen Sie Ihre Anfrage mit den unten beschriebenen Tabs und klicken Sie dann auf Senden.
- Wenn du fertig bist, klicke auf das Symbol "Schließen Probieren" (X), um die Konsole zusammenzuklappen und mit der Dokumentation fortzufahren.
Die Konsole öffnet sich an Ort und Stelle – du bleibst die ganze Zeit auf derselben Endpunktseite, wobei die Dokumentation noch sichtbar darüber ist.
Eine Anfrage erstellen
Der Request Builder ist in Tabs organisiert. Welche Tabs erscheinen, hängt von der HTTP-Methode des Endpunkts ab:
- Params — Pfad- und Abfrageparameter, die für den Endpunkt definiert sind. Erforderliche Parameter sind markiert, und jeder zeigt seine Beschreibung aus deiner Spezifikation an.
- Autorisierung – die Authentifizierungsmethode und die Zugangsdaten für das Sicherheitsschema des Endpunkts. Siehe Autorisierung von Anfragen in der Try It-Konsole.
- Header – Anfrage-Headers.
- Körper – die Anfrage-Nutzlast. Dieser Tab erscheint nur für Methoden, die einen Körper nehmen, wie POST, PUT und PATCH. Es wird bei GET-Anfragen nicht angezeigt.
Während du die Tabs ausfüllst, baut die Konsole die Anfrage im Hintergrund auf. Sie können die zusammengestellte Anfrage jederzeit im Request-Panel rechts ansehen und das entsprechende Code-Beispiel im Code-Panel sehen.
Zusammenarbeit mit dem Antrag
Für Endgeräte, die einen Körper akzeptieren, bietet der Body-Tab einen vollständigen Editor mit Werkzeugen, um deine Nutzlast zu erstellen und zu validieren.
- Nichts / Roh – Wähle, ob du keinen Körper (
none) oder eine rohe Nutzlast (raw) sendst. - Medientyp – wählen Sie den Inhaltstyp für den Hauptteil aus, zum Beispiel
application/json. - Beispiel – fügen Sie eine fertige Beispielnutzlast für den Endpunkt ein, die aus Ihrer Spezifikation generiert wird.
- Aus dem Schema ausfüllen – füllen Sie den Editor mit einem Beispiel-Body aus, der aus dem Request-Schema des Endpunkts erstellt wurde. Dies überschreibt den aktuellen Inhalt des Editors.
- Verschönern – formatiere den Körper mit korrekter Einkerbung, sodass eine verkleinerte oder unordentliche Nutzlast lesbar wird.
- Stellen Sie einen kürzlich gesendeten Körper wieder her – bringen Sie einen Körper zurück, den Sie zuvor in dieser Sitzung geschickt haben. Dadurch werden tatsächlich gesendete Körper wiederhergestellt, sodass du schnell zu einer vorherigen funktionierenden Nutzlast zurückkehren kannst, ohne sie neu eingeben zu müssen.
- Wortumschlag umschalten – wickle lange Zeilen im Editor ein, damit du sie lesen kannst, ohne horizontal zu scrollen.
Fill from Schema ersetzt das, was gerade im Editor ist, durch ein frisches Sample, das aus dem Schema generiert wurde. Wenn du den Text bearbeitet hast, kopiere alles, was du behalten möchtest, bevor du es benutzt.
Validierung anhand des Schemas
Der Body-Editor validiert Ihre Nutzlast beim Tippen gegen das Schema des Endpunkts – nicht nur auf gültiges JSON, sondern darauf, ob die Nutzlast tatsächlich dem entspricht, was der Endpunkt erwartet.
Dies erfasst zwei verschiedene Arten von Problemen:
- Syntaxfehler – die Nutzlast ist nicht gut geformt, zum Beispiel ein fehlendes Komma oder Doppelpunkt. Diese erscheinen als Nachrichten wie "Colon erwartet" oder "Erwartetes Komma".
- Schemafehler – die Nutzlast ist gültiges JSON, stimmt aber nicht mit dem Schema überein. Wenn zum Beispiel ein Feld eine ganze Zahl erwartet und Sie eine Zeichenkette angeben, markiert der Editor "Falscher Typ. Erwartet...". Das Bereitstellen eines Feldes, das das Schema nicht erlaubt, wird als "Eigenschaft nicht erlaubt" markiert.
Wenn Probleme gefunden werden, erscheint unter dem Editor ein Bereich für die Validierung von Fehlern im Körper, der eine Anzahl der Probleme anzeigt. Benutze Sprung zum nächsten Problem, um direkt zu jedem im Editor zu wechseln, und erweitere die Liste, um alle Aufgaben gleichzeitig zu sehen.
Das bedeutet, dass eine Nutzlast vollkommen gültiges JSON sein kann und trotzdem markiert wird – weil Try It! sie mit dem tatsächlichen Schema deiner API abgleicht, wodurch Fehlanpassungen erkannt werden, bevor du die Anfrage sendest, statt nachdem der Server sie abgelehnt hat.
Die Anfrage senden und die Antwort lesen
Sobald Ihre Anfrage fertig ist, klicken Sie auf Anfrage senden. Die Konsole sendet eine Live-Anfrage an deine API und zeigt das Ergebnis im Antwortbereich rechts an.
Die Antwort umfasst:
- Status — der zurückgegebene HTTP-Statuscode, wie
200,401, oder404. - Zeit – wie lange die Anfrage dauerte, in Millisekunden.
- Größe – die Größe des Reaktionskörpers.
- Body- und Header-Tabs – wechseln zwischen der Antwortnutzlast und dem vollständigen Satz der vom Server zurückgegebenen Antwortheaders.
Du kannst die Anfrage- und Antwort-Panels anpassen, indem du den Trenner zwischen ihnen ziehst, wodurch mehr Platz für die Seite entsteht, auf der du arbeitest.
Deine Arbeit ist gerettet
Während du in der Konsole arbeitest, bewahrt Try It! deine Eingabe, damit du sie nicht verlierst, wenn du dich bewegst:
- Parameter, Header, der Request-Body, der ausgewählte Medientyp und der aktive Tab werden beibehalten, wenn du die Endpunkte wechselst und auch wenn du die Konsole während derselben Sitzung schließt und wieder öffnest.
- Zugangsdaten und die letzte Antwort werden nur für die aktive Sitzung gespeichert und nicht gespeichert. Zugangsdaten sind außerdem in der Anfragevorschau zur Sicherheit verdeckt.
Authentifizierung
Entwickler geben Zugangsdaten im Autorisierungstab bereit, wobei sie das Schema verwenden, das Ihre API definiert – API-Schlüssel, HTTP Basic, HTTP Bearer, OAuth 2.0 oder OpenID Connect. Try It! liest die Schemata aus deiner OpenAPI-Spezifikation und zeigt für jedes die richtigen Felder an.
Für vollständige Details zu jeder Methode – einschließlich der Definition in deiner Spezifikation und wie die OAuth 2.0-Anmeldung in der Konsole funktioniert – siehe Autorisierung von Anfragen in der Try It-Konsole.
Try It! unterstützt mehrere Sicherheitsschemata, sodass Entwickler Endpunkte testen können, die mehr als eine Authentifizierungsmethode erfordern.
Verwendung von Variablen
Variablen erlauben es Entwicklern, einen Wert einmal zu speichern und ihn über Endpunkte hinweg mit einem {{placeholder}} zu verwenden – nützlich für Werte wie eine ID oder ein Token, die sich über viele Anfragen hinweg zurückholen. Du kannst eine Variable in jedes Feld einfügen, und die Anfrage-Vorschau zeigt an, dass sie auf ihren tatsächlichen Wert aufgelöst wurde.
Wie man Variablen erstellt, verwaltet und wiederverwendet, siehe Verwendung von Variablen in der Try It-Konsole.
Voraussetzungen dafür, dass Try It! erscheinen kann
Try It! erscheint nur auf einer Endpunktseite, wenn Ihre API-Spezifikationsdatei Folgendes korrekt definiert:
- Eine Server-URL – der
serversAbschnitt deiner Spezifikation muss mindestens eine gültige Basis-URL enthalten. - Eine Servervariable (optional) – falls verwendet, muss die Variable neben der URL definiert werden.
Wenn die Server-URL fehlt, wird der Try It!-Button auf der Knowledge Base-Seite nicht sichtbar sein.
Korrektes Server-URL-Format
servers:
- url: https://api.yourdomain.com
description: Production
Für APIs mit mehreren Regionen definieren Sie mehrere Einträge:
servers:
- url: https://api.yourdomain.com
description: Global
- url: https://api.us.yourdomain.com
description: US region
Die oben genannten URLs sind Beispiele. Verwenden Sie die eigentliche Basis-URL für Ihre API.
Was Try It! nicht unterstützt
- Webhooks – Try It! ist für Webhook-Definitionen nicht verfügbar. Webhook-Seiten zeigen das Nutzlastschema und ein Beispiel, können aber keine Testanfragen senden.
FAQ
Warum wird die Anfrage über api/apidocs/tryit-proxy weitergeleitet?
Das ist erwartetes Verhalten. Anfragen werden über den api/apidocs/tryit-proxy Endpunkt geleitet, um CORS-Fehler (Cross-Origin Resource Sharing) zu vermeiden. Es beeinflusst die Funktionalität nicht – Anfragen liefern trotzdem die korrekten Ergebnisse von deiner API.
Warum gibt es bei manchen Endpunkten keinen Body-Tab?
Der Body-Tab erscheint nur für Methoden, die eine Anfragenutzlast aufnehmen, wie POST, PUT und PATCH. GET-Anfragen nehmen keinen Körper an, daher wird der Tab für sie nicht angezeigt.
Mein Antragstext ist gültiges JSON, aber der Editor markiert trotzdem ein Problem. Warum?
Try It! validiert den Körper gegen das Schema des Endpunkts, nicht nur für gut formierte JSON. Eine Nutzlast kann gültiges JSON sein, aber dennoch nicht mit dem Schema übereinstimmen – zum Beispiel durch das Senden einer Zeichenzeichenkette, bei der eine ganze Zahl erwartet wird, oder das Einfügen eines Feldes, das das Schema nicht erlaubt. Der Validierungsbereich zeigt, was sich ändern muss.
Sind die Zugangsdaten, die ich in Try It! eingebe, gespeichert?
Nein. Zugangsdaten und die letzte Antwort werden nur für die aktive Sitzung gespeichert und nicht gespeichert. Parameter, Header, der Anforderungskörper, der ausgewählte Medientyp und der aktive Tab werden während der Arbeit erhalten, aber die Zugangsdaten sind nur sitzungsbasiert und werden in der Anfragevorschau verdeckt.
Kann ich Endpunkte testen, die mehr als eine Authentifizierungsmethode erfordern?
Ja. Try It! unterstützt mehrere Sicherheitskonzepte, aber nicht gleichzeitig. Man kann Zugangsdaten für ein Schema nach dem anderen konfigurieren und senden. Details finden Sie unter Autorisierung von Anfragen in der Try It-Konsole .
Kann ein KI-Agent innerhalb desselben Workflows zwischen MCP und der Standard-API wechseln?
Ja. Ein einzelner Workflow kann MCP für die Argumentations- und Handlungsschritte verwenden – Suche, Lesen, Schreiben und direkt das Aufrufen der Standard-API für Operationen außerhalb des MCP-Bereichs. Die beiden Schnittstellen schließen sich nicht gegenseitig aus; Sie greifen auf dieselbe zugrundeliegende Wissensbasis zu.