Teste Endpunkte mit Try it!

Try It! ist die interaktive API-Konsole 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 Try It! funktioniert, was Entwickler benötigen, um es zu verwenden, und wie man jede unterstützte Authentifizierungsmethode in Ihrer API-Spezifikation konfiguriert.

Was Try It! tut

Von jeder Endpunktseite in Ihrer veröffentlichten API-Referenz aus können Entwickler:

• Wählen Sie eine HTTP-Methode und einen Endpunkt aus
• Füllen Sie erforderliche und optionale Parameter aus
• Konfigurieren Sie Authentifizierungszugangsdaten
• Senden Sie eine Live-Anfrage und sehen Sie die Antwort in Echtzeit an
  

Voraussetzungen dafür, dass Try It! erscheinen kann

Try It! erscheint nur auf einer Endpunktseite, wenn beide Folgendes korrekt in deiner API-Spezifikationsdatei definiert sind:

• Eine Server-URL – der servers Abschnitt deiner Spezifikation muss mindestens eine gültige Basis-URL enthalten.
• Eine Servervariable – die Variable muss neben der URL definiert werden.

Wenn eines davon 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

Wie Anfragen weitergeleitet werden

Wenn ein Entwickler auf Try it & see response klickt, wird die Anfrage-URL zur Basis-URL Ihrer API hinzugefügt tryit.document360.io . Zum Beispiel:

https://tryit.document360.io/https://api.yourdomain.com/v2/your-endpoint

Das ist erwartetes Verhalten. Die tryit.document360.io Subdomain wird intern verwendet, um API-Testanfragen zu routen und zu verarbeiten. Es beeinflusst die Funktionalität nicht, aber Anfragen liefern trotzdem die korrekten Ergebnisse von deiner API.

Unterstützte Authentifizierungsmethoden

Document360 liest die Authentifizierungskonfiguration direkt aus Ihrer OpenAPI-Spezifikation und zeigt sie an zwei Orten an: in der Endpunkt-Dokumentation und in der Try It!-Konsole.

Authentifizierungsmethoden werden in Ihrer OpenAPI-Spezifikation components/securitySchemes definiert und auf einzelne Endpunkte mit dem Feld security angewendet.

Grundlegende Authentifizierung

Die grundlegende Authentifizierung erfordert einen Benutzernamen und ein Passwort, der in der Authorization Kopfzeile jeder Anfrage kodiert und weitergegeben wird.

In Ihrer OpenAPI-Spezifikation:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

Wenden Sie es auf einen Endpunkt an:

/your-endpoint:
  get:
    security:
      - basicAuth: []

In Try It! werden Entwickler aufgefordert, vor dem Senden einer Anfrage einen Benutzernamen und ein Passwort einzugeben.

Inhabermarker

Die Trägertoken-Authentifizierung verwendet ein Token, das im Header Authorization als übergeben wird Bearer <token>.

In Ihrer OpenAPI-Spezifikation:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

Wenden Sie es auf einen Endpunkt an:

/your-endpoint:
  get:
    security:
      - BearerAuth: []

API-Schlüssel

Die API-Schlüssel-Authentifizierung verwendet einen eindeutigen Schlüssel, der in den Anfrageheadern übergeben wird.

In Ihrer OpenAPI-Spezifikation:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Wenden Sie es auf einen Endpunkt an:

/your-endpoint:
  get:
    security:
      - ApiKeyAuth: []

In Try It! werden Entwickler aufgefordert, ihren API-Schlüsselwert einzugeben. Er wird in dem in deiner Spezifikation definierten Header-Namen gesendet (im obigen BeispielX-API-Key ).

OAuth2

OAuth2 wird mit vier Flows unterstützt. Verwenden Sie den Flow, der mit der Art und Weise übereinstimmt, wie Ihre API Zugriffstoken ausgibt.

Erforderliche Konfiguration für Try It!

Wenn Ihre API OAuth2 verwendet, müssen zwei zusätzliche Einstellungen konfiguriert werden:

Umleiten der URI — Nachdem ein Entwickler den OAuth-Autorisierungsprozess abgeschlossen hat, wird er zurück zu Document360 weitergeleitet. Fügen Sie die Redirect-URI von Document360 zur Liste der erlaubten Redirect-URIs Ihres OAuth-Anbieters hinzu:

https://your-apidocs-domain.com/oauth

Ersetze your-apidocs-domain.com sie durch die Domain, auf der deine Document360-API-Dokumentation veröffentlicht wurde.

Stille Verlängerung — Document360 aktualisiert das OAuth-Zugriffstoken automatisch im Hintergrund, während ein Entwickler Try It! aktiv verwendet. Das verhindert, dass die Sitzung mitten im Gebrauch abläuft. Für dich ist keine Konfiguration erforderlich, da dies automatisch von Document360 gehandhabt wird.

Beispiel für eine Spezifikationsdefinition (Autorisierungscode-Fluss)

components:
  securitySchemes:
    oauth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.yourdomain.com/oauth/authorize
          tokenUrl: https://auth.yourdomain.com/oauth/token
          scopes:
            read: Read access
            write: Write access

OpenID Connect

OpenID Connect erweitert OAuth2 durch die Hinzufügung der Benutzeridentitätsverifikation. Es ist ähnlich wie OAuth2 konfiguriert und hat die gleichen Anforderungen an Redirect-URI und stille Verlängerung.

In Ihrer OpenAPI-Spezifikation:

components:
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration

Die gleiche Redirect-URI-Anforderung gilt:

https://your-apidocs-domain.com/oauth

Anwendung mehrerer Sicherheitsschemata auf einen Endpunkt

Wenn ein Endpunkt gleichzeitig mehr als eine Authentifizierungsmethode benötigt, definieren Sie diese gemeinsam unter security Operationen:

/secure-endpoint:
  get:
    security:
      - BearerAuth: []
        ApiKeyAuth: []

Dafür müssen sowohl ein Bearer-Token als auch ein API-Schlüssel bereitgestellt werden, bevor die Anfrage gesendet werden kann. Try It! unterstützt mehrere Sicherheitsschemata in einer einzigen Sitzung.

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.
• Instanzbasierte dynamische Antworten – Document360 folgt der OpenAPI-Spezifikation, die eine konsistente statische Struktur für Anfrage- und Antwortobjekte definiert. Wenn deine API unterschiedliche Antworten für denselben Endpunkt über verschiedene Umgebungen oder Instanzen hinweg zurückgibt, spiegelt Try It! nur das wider, was in der Spezifikation definiert ist.

FAQ