APIs mit SmartDocs dokumentieren

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Mit SmartDocs können Sie Ihre APIs auf dem Drupal 7-Entwicklerportal so dokumentieren, dass die API-Dokumentation vollständig interaktiv wird. Durch die interaktive Dokumentation können Portalnutzer:

  • Informationen zu Ihren APIs
  • Live-Anfrage an API senden
  • Von der API zurückgegebene Live-Antwort ansehen

Durch das Erstellen einer interaktiven Dokumentation zu Ihren APIs erleichtern Sie dem Portalnutzer das Erlernen, Testen und Bewerten der APIs.

Die Edge Management API ist eine RESTful API, mit der Sie mit einem beliebigen HTTP-Client auf API-Dienste zugreifen können. Apigee verwendet SmartDocs, um interaktive Dokumentation für die Edge-Verwaltungs-API zu erstellen. Die API-Dokumentation finden Sie hier.

Beispiel für ein SmartDocs-Portal

Zur Verwendung von SmartDocs benötigen Sie ein Apigee Developer Services-Portal. Weitere Informationen finden Sie unter Entwicklerportal erstellen.

Klicken Sie auf der Startseite des Entwicklerportals in der oberen Navigationsleiste auf APIs, um die Seite mit der API-Dokumentation aufzurufen.

Im Portal sind zwei APIs dokumentiert: Hello World und Pet Store Example.

Die Hello World API wurde aus der simulierten OpenAPI-Spezifikation mocktarget.yaml erstellt. Weitere Informationen finden Sie unter https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

Die Pet Store Example API wurde aus der Demo für die klassische Zoohandlung erstellt.

Sehen Sie sich die Hello World API an:

  1. Klicken Sie auf Hello World API. Die Übersichtsseite der Hello World API wird angezeigt:
  2. Klicken Sie auf API-Bestätigung ansehen. Die SmartDocs für diese Ressource wird angezeigt:
  3. Klicken Sie auf Anfrage senden.
  4. Sehen Sie sich die zurückgegebene Antwort an: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. Klicken Sie auf den Tab Anfrage, um die Anfrage aufzurufen, oder auf den Tab cURL, um den entsprechenden cURL-Aufruf anzusehen.

APIs mit SmartDocs dokumentieren

SmartDocs stellt Ihre APIs mithilfe eines model dar, das alle Informationen zu Ihren APIs enthält. Das Portal extrahiert Informationen über Ihre APIs aus dem Modell, um die Dokumentationsseiten im Portal als Drupal-Knoten zu rendern, wobei jeder Drupal-Knoten einer Seite mit Dokumentation im Portal entspricht.

Im Allgemeinen gehen Sie bei der Verwendung von SmartDocs wie folgt vor:

  1. Konfigurieren Sie das Drupal SmartDocs-Modul im Portal.
  2. Erstellen Sie ein SmartDocs-Modell.
  3. Fügen Sie dem Modell APIs über eine WADL-Datei, OpenAPI (früher Swagger) oder manuell hinzu.
  4. Rendern Sie das Modell als Sammlung von Drupal-Knoten. Jeder Drupal-Knoten enthält Informationen zu einer einzelnen API. Wenn beispielsweise eine Ressource in Ihrer API sowohl eine POST- als auch eine PUT-Anfrage unterstützt, erstellt SmartDocs einen separaten Drupal-Knoten für POST und PUT.
  5. Veröffentlichen Sie die Drupal-Knoten. Nach der Veröffentlichung können Ihre Portalnutzer die API ansehen und mit ihr interagieren.
  6. Bearbeiten Sie die Drupal-Knoten vor oder nach der Veröffentlichung. Sie können die Drupal-Knoten mit dem Drupal-Editor oder durch Bearbeiten der ursprünglichen WADL-Datei oder der OpenAPI-Spezifikation bearbeiten. Wenn Sie mit dem Bearbeiten der WADL-Datei oder der OpenAPI-Spezifikation fertig sind, importieren Sie diese als neue Überarbeitung in das Modell. Rendern und veröffentlichen Sie dann Ihre Änderungen.
  7. Aktivieren Sie TLS. Da SmartDocs im Rahmen einer Anfrage an Ihre APIs Authentifizierungsdaten an Ihr Back-End senden kann, sollten Sie TLS auf Ihrem Portal aktivieren, damit diese Anmeldedaten sicher sind. In den Portal-Produktions- und Testumgebungen stellt Apigee das für https://-Anfragen erforderliche TLS-Zertifikat bereit. Bevor Sie das Portal veröffentlichen, müssen Sie jedoch ein eigenes TLS-Zertifikat abrufen und TLS aktivieren. Weitere Informationen finden Sie unter TLS im Portal verwenden.

SmartDoc-Modelle und -Vorlagen

Wenn Sie ein Modell in Ihrem Portal erstellen, wird das Modell tatsächlich in Ihrer Edge-Organisation und nicht in Drupal gespeichert. Ein Modell ist ein großer Block von JSON mit einem internen Namen (z. B. "my-smartdocs-api") und definiert die Struktur einer API. Ihr Portal hingegen rendert das Modell in HTML und bietet eine Bearbeitungsschnittstelle für das Modell. Alle Aktualisierungen der API im Portal werden automatisch zurück auf das Quellmodell übertragen.

In Organisation gespeichert

In Drupal gespeichert

Modelle

Vorlagen

Drupal-Knoten mit Bearbeitungsfunktionen

Angenommen, Sie haben mehrere Portale in Ihrer Organisation (z. B. Entwicklung, Phase und Produktion). In Pantheon verschieben Sie ein Portal von einer Umgebung in eine andere. Jede Instanz des Portals scheint ein eigenes Modell zu enthalten, aber alle verweisen tatsächlich auf das Quellmodell. Wenn Sie die API in der Entwicklerversion bearbeiten, wird das Modell aktualisiert und die Änderungen werden in der Produktion angezeigt. Wenn Sie ein Modell in der Entwicklung löschen, wird ebenfalls die Quelle gelöscht und ist in der Produktion nicht mehr verfügbar.

Vorlagen steuern das Design Ihrer SmartDocs und diese Vorlagen (gesteuert von Handles und CSS-Dateien) werden mit jeder Portalinstanz gespeichert. Jedes Portal kann theoretisch eine eindeutige Vorlage für jedes Modell verwenden. Einer der Vorteile des Rendering-Frameworks besteht jedoch darin, dass eine Standardvorlage (entweder die Apigee-Standardvorlage oder eine von Ihnen bereitgestellte Vorlage) automatisch auf jedes Modell angewendet wird.

Das folgende Diagramm zeigt die Beziehung zwischen Modellen und Portalen. Die grünen Pfeile stehen für die automatische Synchronisierung.

Mit dem folgenden cURL-Befehl werden alle Modelle in Ihrer Organisation aufgelistet:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

SmartDocs-Modul konfigurieren

Apigee hat SmartDocs als benutzerdefiniertes Drupal-Modul implementiert. Gehen Sie so vor, um das SmartDocs-Modul zu konfigurieren.

So konfigurieren Sie das SmartDocs-Modul:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Drupal-Verwaltungsmenü Module aus. Die Liste aller installierten Drupal-Module wird angezeigt.
  3. Aktivieren Sie das SmartDocs-Modul.
  4. Speichern Sie die Konfiguration.
  5. Wählen Sie im Drupal-Admin-Menü Modules (Module) aus.
  6. Wählen Sie SmartDocs -> Berechtigungen aus und vergewissern Sie sich, dass für die Rolle „Administrator“ die Option „Verwaltungsaufgaben für das SmartDocs-Modul durchführen“ aktiviert ist.
  7. Wählen Sie im Drupal-Verwaltungsmenü Configuration > Dev Portal (Konfiguration > Entwicklerportal) aus.
  8. Legen Sie für Zeitüberschreitung der Verbindung und Zeitlimit für Anfragen 16 Sekunden fest.
  9. Speichern Sie die Konfiguration.
  10. Konfigurieren Sie die URL-Einstellungen:
    1. Wählen Sie im Drupal-Menü Konfiguration > Suche und Metadaten > URL-Aliasse > Einstellungen aus.
    2. Legen Sie Maximale Aliaslänge und Maximale Komponentenlänge auf 255 fest.
    3. Maximieren Sie Zeichensetzung.
    4. Wählen Sie für die Einstellungen für linke geschweifte Klammer ({) und rechte geschweifte Klammer (}) die Option Keine Aktion (nicht ersetzen) aus.
    5. Klicken Sie auf Save configuration (Konfiguration speichern).
  11. Wenn Ihr Entwicklerportal Nutzern in einem internen Netzwerk ohne Internetzugriff zugänglich gemacht wird oder wenn sich ein Teil Ihrer APIs in einem privaten Netzwerk befindet, konfigurieren Sie die SmartDocs API-Proxy-URL so:
    1. Wählen Sie im Drupal-Administrationsmenü Configuration > SmartDocs (Konfiguration > SmartDocs).
    2. Maximieren Sie Erweiterte Einstellungen.
    3. Aktualisieren Sie das Feld SmartDocs-Proxy-URL so: <host>/smartdocs/v1/sendrequest.
      Die Inline-Hilfe sollte den erforderlichen Wert für Ihre Umgebung enthalten. Beispiel:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      Die Standardeinstellung für dieses Feld ist https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest.
    4. Klicken Sie auf Save configuration (Konfiguration speichern).

Modell erstellen

Ein Modell enthält alle Informationen zur Darstellung Ihrer API. Sie können mehrere Modelle im Portal definieren, um verschiedene APIs zu unterstützen, oder alle APIs in einem einzigen Modell zusammenfassen.

Jedes Modell gibt einen eindeutigen internen Namen an, der auch die Basis-URL der generierten Drupal-Knoten definiert. Die URL jedes Drupal-Knotens hat das folgende Format:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

Dabei gilt:

  • drupalBasePath: Die Basis-URL Ihres Portals.
  • internalName: Der interne Name des Modells.
  • httpMethod: Die HTTP-Methode der API, z. B. get, put, post oder delete.
  • resourcePath: Der Ressourcenpfad.

Wenn Sie den internen Namen beispielsweise als „mymodel“ angeben, lautet die URL für den generierten Drupal-Knoten für eine GET-Anfrage an eine Ressource mit dem Namen „/books“:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

So erstellen Sie ein Modell

Wenn Sie ein Modell erstellen, wird es in Ihrer Edge-Organisation als Quelle für die API-Struktur gespeichert. Weitere Informationen finden Sie unter SmartDoc-Modelle und Vorlagen.

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Drupal-Verwaltungsmenü Content > SmartDocs aus.
  3. Wählen Sie oben auf der Seite Neues Modell aus.
  4. Füllen Sie die folgenden Felder aus:
    • Name: Der Modellname, der auf der gesamten Website angezeigt wird.
    • Interner Name: Wenn Sie den Namen eingeben, wird der interne Name angezeigt. Der interne Name für das Modell, der unter allen Modellen eindeutig sein muss. Der interne Name darf nur Kleinbuchstaben, Ziffern und Bindestriche ohne Leerzeichen enthalten. Wählen Sie Bearbeiten aus, um diesen Namen zu bearbeiten.
    • Beschreibung: Eine Beschreibung des Modells.
  5. Wählen Sie Modell erstellen aus.

Nachdem Sie das Modell erstellt haben, werden Sie zur Seite des Modells weitergeleitet. Von dort aus können Sie das Drop-down-Menü „Vorgänge“ bx für Folgendes verwenden:

  • Importieren Sie eine WADL-Datei, die Ihre API beschreibt, oder geben Sie die URL einer OpenAPI-Spezifikation an, die Ihre API beschreibt.
  • Überarbeitung zum Modell hinzufügen
  • Ändern Sie die Einstellungen des Modells, einschließlich der vom Modell verwendeten Stylesheets.
  • Exportieren Sie das Modell in eine Datei.
  • Löschen Sie das Modell.

APIs zu einem Modell hinzufügen

So fügen Sie einem Modell APIs hinzu:

  • WADL-Datei mit der API-Definition importieren
  • OpenAPI-Spezifikation importieren (OpenAPI 2.0 oder 1.2)
  • Ressourcen und Methoden manuell erstellen

Sie können auch eine SmartDocs-JSON-Datei in ein Modell importieren. Zum Erstellen dieser Datei exportieren Sie in der Regel zuerst ein vorhandenes Modell, bearbeiten die Datei und importieren dann die Aktualisierungen. Weitere Informationen finden Sie unter Modell exportieren und importieren.

Video: In einem kurzen Video erfahren Sie, wie Sie einem SmartDocs-Modell APIs hinzufügen, indem Sie eine OpenAPI-Spezifikation importieren.

WADL importieren

Nachdem Sie ein Modell erstellt haben, importieren Sie eine WADL-Datei, in der Ihre API beschrieben wird. Jedes Mal, wenn Sie eine WADL-Datei importieren, erstellen Sie automatisch eine neue Version des Modells.

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie das Modell aus, das Sie aktualisieren möchten.
  4. Wählen Sie unter Vorgänge die Option Importieren aus.
  5. Wählen Sie auf der SmartDocs-Importseite im Drop-down-Menü Format auswählen die Option WADL aus.
  6. Wählen Sie im Drop-down-Menü Uploadtyp die Option Datei oder URL aus.
    1. Wenn Sie Datei auswählen, gehen Sie zur WADL-Datei.
    2. Wenn Sie URL auswählen, geben Sie die URL der WADL-Datei an.
  7. Klicken Sie auf Importieren, um es in das Modell zu importieren. Sie können das Modell jetzt rendern.
  8. Sie werden zur Informationsseite des Modells weitergeleitet. Dort können Sie das Modell jetzt rendern.

OpenAPI-Spezifikation importieren

Nachdem Sie ein Modell erstellt haben, können Sie eine OpenAPI-Spezifikation (früher Swagger) importieren. Edge unterstützt die OpenAPI-Versionen 1.2 und 2.0.

OpenAPI verwendet Dateien, die JSON-Objekte enthalten, um eine API zu beschreiben. Jedes Mal, wenn Sie eine OpenAPI-Spezifikation importieren, erstellen Sie automatisch eine neue Version des Modells.

So importieren Sie eine OpenAPI-Spezifikation:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie das Modell aus, das Sie aktualisieren möchten.
  4. Wählen Sie unter Vorgänge die Option Importieren aus.
  5. Wählen Sie auf der SmartDocs-Importseite im Drop-down-Menü Format auswählen die Option Swagger JSON oder Swagger YAML aus.
  6. Wählen Sie im Drop-down-Menü Upload Type (Uploadtyp) die Option File (Datei) oder URL (URL) aus. Für OpenAPI 1.2 müssen Sie URL auswählen.
    1. Wenn Sie Datei auswählen, gehen Sie zur OpenAPI-Spezifikation.
    2. Wenn Sie URL auswählen, geben Sie die URL der OpenAPI-Spezifikation an.
  7. Klicken Sie auf Importieren, um es in das Modell zu importieren.
  8. Sie werden zur Informationsseite des Modells weitergeleitet. Dort können Sie das Modell jetzt rendern.

Ressourcen und Methoden manuell erstellen

Wenn Sie keine WADL-Datei oder OpenAPI-Spezifikation für Ihre API haben, können Sie Ihrem Modell manuell APIs hinzufügen. Wenn Sie eine WADL-Datei oder eine OpenAPI-Spezifikation zum Erstellen Ihres Modells verwenden, können Sie mit diesem Verfahren Ihre APIs nach dem Import bearbeiten, einschließlich des Hinzufügens neuer APIs.

So fügen Sie eine API manuell hinzu:

  1. Erstellen Sie eine neue Version des Modells.

    Wenn Sie die Überarbeitung erstellen, geben Sie den Basispfad aller APIs im Modell an. Das bedeutet, dass alle APIs in einem Modell denselben Basispfad verwenden. Geben Sie den Basispfad beispielsweise so an:

    https://myCompany.com/v1

    Wenn Sie dem Modell Ressourcen hinzufügen, wird der Basispfad erweitert.
  2. Definieren Sie eine oder mehrere Ressourcen für das Modell. Der Ressourcenpfad wird mit dem Basispfad der Modellüberarbeitung kombiniert, um die vollständige URL der Ressource anzugeben. Wenn Ihre Ressource beispielsweise den Pfad „/login“ definiert, lautet die vollständige URL der Ressource:

    https://myCompany.com/v1/login
  3. Definieren Sie eine oder mehrere Methoden für jede Ressource. Eine Methode gibt das HTTP-Verb an, das für eine Ressource aufgerufen werden kann. Für die Ressource „/login“ unterstützen Sie beispielsweise POST für die Anmeldung und DELETE für die Abmeldung. Diese Ressource unterstützt keine anderen HTTP-Verben wie PUT oder GET. Definieren Sie daher zwei Methoden für die Ressource, eine für den POST und eine für den DELETE-Vorgang.

    Die Methode verwendet die Ressourcen-URL der übergeordneten Ressource. Daher sind alle Methoden mit derselben URL in einer einzigen Ressource in SmartDocs definiert.

Beachten Sie folgende allgemeine Regeln:

  • Erstellen Sie ein anderes SmartDocs-Modell für jeden eindeutigen Basispfad in Ihrer API.
  • Definieren Sie für jede eindeutige Ressource in Ihrer API eine andere SmartDocs-Ressource.
  • Definieren Sie für jedes von einer Ressource unterstützte HTTP-Verb eine andere SmartDocs-Methode.

Neue Überarbeitung eines Modells erstellen

Sie können eine Ressource nur zu einer vorhandenen Version eines Modells hinzufügen. Wenn das Modell bereits eine Überarbeitung hat, können Sie Ihre Ressource hinzufügen. Wenn das Modell neu ist und keine Überarbeitungen hat, erstellen Sie eine neue Überarbeitung.

So erstellen Sie eine neue Version eines Modells:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter Vorgänge die Option Überarbeitung hinzufügen aus.
  4. Geben Sie auf der Seite API-Überarbeitung hinzufügen die folgenden Informationen ein:
    • Anzeigename: Der Name der Überarbeitung, wie er im Portal angezeigt wird.
    • Versions-ID: Eine kurze Kennung für die Überarbeitung.
    • Beschreibung: Die Beschreibung der Überarbeitung.
    • Basis-URL: Die Basis-URL aller APIs in der Version des Modells. Ein Modell kann für jede Version unterschiedliche Basis-URLs verwenden. Beispielsweise können Sie einen Versionsindikator in die Basis-URL einfügen. Für die erste Modellüberarbeitung lautet die Basis-URL:
      https://myCompany.com/v1
      Für die nächste Überarbeitung könnte die Basis-URL so aussehen:
      https://myCompany.com/v2
  5. Wählen Sie Überarbeitung hinzufügen aus. Sie werden zur Überarbeitungsseite des Modells weitergeleitet. Sie können jetzt Ressourcen für das Modell definieren.

Ressource definieren

Eine Ressource gibt die vollständige URL einer API an. Beim Definieren einer Ressource geben Sie den Ressourcenpfad an, der mit der Basis-URL in der Modellüberarbeitung kombiniert wird, um die vollständige URL der Ressource zu erstellen.

So definieren Sie eine Ressource:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter Vorgänge die Option API-Überarbeitungen aus, um alle Überarbeitungen eines Modells aufzurufen.
  4. Wählen Sie die zu bearbeitende Überarbeitung aus.
  5. Wählen Sie auf der Seite „Überarbeitung“ im Drop-down-Menü die Option Ressource hinzufügen aus.
  6. Geben Sie auf der Seite Ressource hinzufügen die folgenden Informationen ein:
    • Anzeigename: Der Name der Ressource.
    • Pfad: Der Ressourcenpfad, der mit "/" beginnt. Der Wert von Path wird mit der Basis-URL der Modellüberarbeitung kombiniert, um die vollständige URL der Ressource zu erstellen.
    • Beschreibung: Eine Beschreibung der Ressource.
    • Parameter: Geben Sie optional das JSON-Objekt ein, das die einzelnen Parameter der Ressource definiert. Diese Parameter werden unten beschrieben.
  7. Wählen Sie Ressource hinzufügen aus. Sie werden zur Modellseite weitergeleitet. Sie können jetzt Methoden für die Ressource definieren.

Optional können Sie der Ressource Parameter hinzufügen, z. B. Vorlagen-, Abfrage- und Headerparameter. Alle Ressourcenparameter werden von allen für diese Ressource definierten Methoden übernommen. Wenn Sie einen Abfrageparameter für die Ressource definieren, müssen daher alle der Ressource hinzugefügten Methoden diesen Abfrageparameter unterstützen.

Alternativ können Sie Parameter für eine Methode definieren. Beispielsweise kann eine POST-Methode Abfrageparameter unterstützen, die von einer DELETE-Methode nicht unterstützt werden. Fügen Sie daher beim Definieren der Methode wie unten beschrieben spezifische Parameter für eine Methode hinzu.

In der folgenden Abbildung sehen Sie eine vorhandene SmartDocs-Seite für die API zum Genehmigen oder Aufheben der Entwickler-App von Apigee. Dabei sind alle Parametertypen hervorgehoben:

Jeder Parametertyp wird durch ein JSON-Objekt definiert:

Typ

JSON-Objekt

Hinweise

Vorlage

{
"dataType": "string",
"defaultValue": "",
"description": "Name der Organisation.",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

Vorlagenparameter sind immer erforderlich. Setzen Sie daher required auf true und lassen Sie den Wert auf defaultValue weg.

Der Wert description wird in einem Pop-up angezeigt, wenn der Nutzer den Mauszeiger auf die URL einer SmartDocs-Seite bewegt.

Abfrage

{
"dataType": "string",
"defaultValue": "",
"description": "Der Standort.",
"name": "w",
"required": true,
"type": "QUERY"
}

Erforderliche Abfrageparameter können immer noch einen defaultValue angeben, tun dies aber häufig nicht.

Für optionale Abfrageparameter müssen Sie required auf false setzen und einen Wert auf defaultValue angeben.

Header

{
"dataType": "string",
"defaultValue": "application/json",
"description": "Als <code>application/json</code> angeben",
"name": "Content-Type",
"required": true,
"type": "HEADER"
}

Beachten Sie, wie Sie HTML-Tags in der Beschreibung verwenden können.

Ein Vorlagenparameter definiert eine Variable im Ressourcenpfad. Sie definieren beispielsweise zwei Vorlagenparameter für die Ressource. Beachten Sie, dass jede Parameterdefinition im Parameterarray durch ein Komma getrennt ist:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Sie können dann die Vorlagenparameter in der Ressourcenpfaddefinition verwenden, die in „{}“ eingeschlossen ist. Geben Sie beispielsweise folgenden Pfad an:

/login/{org_name}/{developer_email}

Auf der SmartDocs API-Seite muss der Nutzer die URL bearbeiten, um den Teil org_name und developer_email der URL anzugeben, bevor er eine Anfrage senden kann.

Methode definieren

Definieren Sie eine oder mehrere Methoden für jede Ressource. Die Methodendefinition gibt ein HTTP-Verb an, das für die Ressource aufgerufen werden kann. Für eine Ressource kann eine einzelne Methode oder mehrere Methoden definiert sein.

Geben Sie beim Definieren der Methode alle von der Methode verwendeten Parameter an, einschließlich Abfrage- und Headerparameter. Weitere Informationen zum Hinzufügen von Parametern zu einer Methode finden Sie in der Beschreibung oben.

Die folgende Abbildung zeigt eine vorhandene SmartDocs-Seite für die Apigee Create Developer API. Jeder Bereich der Seite ist mit dem entsprechenden Wert markiert, den Sie beim Definieren einer Methode festgelegt haben:

Im nächsten Bild ist die gleiche Seite zu sehen, aber die Option „Description of the Request Body“ ist ausgewählt:

So definieren Sie eine Methode:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter Vorgänge die Option API-Überarbeitungen aus, um alle Überarbeitungen eines Modells aufzurufen.
  4. Wählen Sie die zu bearbeitende Überarbeitung aus.
  5. Wählen Sie auf der Überarbeitungsseite aus dem Drop-down-Menü für eine der Ressourcen die Option Methode hinzufügen aus.
  6. Geben Sie auf der Seite Methode bearbeiten die folgenden Informationen ein:
    • Anzeigename: Der Name der API, der auch der Titel der Drupal-Seite für die API wird.
    • Beschreibung: Beschreiben Sie die API.
    • Method Verb: Der HTTP-Verbtyp.
    • Sicherheitsschemas: Geben Sie gegebenenfalls den Authentifizierungsmodus für die Methode an. Weitere Informationen finden Sie unter SmartDocs-Authentifizierungstyp konfigurieren.
    • Inhaltstyp: Der Inhaltstyp der Anfrage und Antwort. Informationen zum Konfigurieren verschiedener Authentifizierungsmethoden finden Sie unten im Abschnitt.
    • Parameter (optional): Alle Abfrage- oder Headerparameter für die Methode. Weitere Informationen zum Hinzufügen eines Parameters zu einer Ressource finden Sie in der Beschreibung oben.
    • Dokumentation zum Anfragetext: (Optional) Beschreiben Sie den Anfragetext. Die Methoden POST und PUT verwenden einen Anfragetext. Hier kannst du sie beschreiben. Wenn Sie diesen Wert weglassen, wird der Link Beschreibung unter Anfragetext auf der generierten SmartDocs-Seite weggelassen.
    • Beispiel für den Anfragetext: (Optional) Zeigen Sie ein Beispiel für einen Anfragetext, in der Regel als JSON-Objekt oder XML. Für die POST- und PUT-Verben wird das Beispiel für den Anfragetext als Teil jeder Anfrage übergeben. Nutzer der SmartDocs-Seite bearbeiten dieses Beispiel, bevor sie eine Anfrage an die API senden. Wenn Sie diesen Wert weglassen, wird der Link Wert unter Anfragetext auf der generierten SmartDocs-Seite weggelassen.
    • Tags: Ein Array von Tags, die mit der API verknüpft sind. SmartDocs verwendet Tags, um ähnliche APIs zu gruppieren. Sie können beispielsweise das Tag „Statistiken“ auf alle APIs zu Statistiken anwenden. Sie können APIs aus verschiedenen Ressourcen unter einem einzigen Tag gruppieren, wenn alle dasselbe Tag verwenden.
  7. Wählen Sie Methode hinzufügen aus. Sie werden zur Modellseite weitergeleitet. Sie können die Methode jetzt rendern und veröffentlichen.

Modell rendern

Nachdem Sie einem Modell APIs hinzugefügt haben, können Sie das Modell rendern. Beim Rendern wird die Beschreibung der API des Modells in Drupal-Knoten umgewandelt. Wenn das Rendern abgeschlossen ist, haben Sie einen einzelnen Drupal-Knoten für jede API, wobei jeder Drupal-Knoten einer HTML-Seite entspricht.

Sie können das gesamte Modell auf einmal rendern oder einzelne APIs für das Rendering auswählen.

So rendern Sie ein Modell:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie rendern möchten, unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie die Überarbeitung aus, die Sie rendern möchten. Sie können nur Knoten aus einer einzelnen Version des Modells rendern.
  5. Wählen Sie die zu rendernden Methoden aus.
  6. Wählen Sie im Drop-down-Menü Update options (Aktualisierungsoptionen) die Option Render Nodes (Renderingknoten) aus.
  7. Klicken Sie auf Aktualisieren.
  8. Es wird ein Ladebildschirm angezeigt, auf dem der Fortschritt der gerade gerenderten Knoten zu sehen ist.
    Nachdem die Knoten gerendert wurden, wird die ID des Drupal-Knotens für jede API in der Spalte Knotenverknüpfung des Modells angezeigt. Klicken Sie auf den Link in der Spalte Knotenverknüpfung, um den gerenderten Knoten zu sehen.

Anstatt Render-Knoten auszuwählen, können Sie Render- und Veröffentlichen-Knoten auswählen, um die APIs als Drupal-Knoten zu rendern und sofort zu veröffentlichen.

Knoten veröffentlichen

Ein Knoten ist für Portalnutzer erst sichtbar, nachdem er veröffentlicht wurde. Optional können Sie Knoten während des Renderingprozesses veröffentlichen. Wenn Sie die Knoten nicht veröffentlichen, müssen Sie sie nach Abschluss des Renderings manuell veröffentlichen.

So veröffentlichen Sie einen Knoten:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie veröffentlichen möchten, unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie die Überarbeitung aus, die Sie veröffentlichen möchten. Sie können nur Knoten von einer einzelnen Version des Modells veröffentlichen.
  5. Wählen Sie die Veröffentlichungsmethoden aus.
  6. Wählen Sie die zu veröffentlichenden Knoten in der Überarbeitung aus.
  7. Wählen Sie in der Drop-down-Liste Update options die Option Publish Nodes (Knoten veröffentlichen) aus.
  8. Klicken Sie auf Aktualisieren.
  9. Navigieren Sie zu dem Knoten, indem Sie die Knoten-ID in der Spalte Knotenverknüpfung auswählen.

Standardmäßig hat die Drupal-URL zu einem veröffentlichten API-Knoten das folgende Format: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. Verwenden Sie das folgende Verfahren, um die Form der URL festzulegen:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Konfiguration > Suche und Metadaten > URL-Aliase > Muster.
  3. Geben Sie unter Muster für alle SmartDocs-Methodenpfade an, wie der Pfad generiert werden soll.
  4. Wählen Sie Konfiguration speichern aus.

Aufgrund des Cachings im Portal werden Ihre Modellseiten möglicherweise nicht sofort nach der Veröffentlichung angezeigt. Bei Bedarf können Sie den HTML-Cache von SmartDocs manuell löschen. Gehen Sie dazu so vor:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Konfiguration > SmartDocs aus.
  3. Klicken Sie auf SmartDocs-Modell-Caches neu erstellen.

Veröffentlichung eines Knotens aufheben

Sie können die Veröffentlichung eines veröffentlichten Knotens jederzeit aufheben. Wenn Sie die Veröffentlichung eines Knotens aufheben, ist er für Portalnutzer unsichtbar.

So heben Sie die Veröffentlichung eines Knotens auf:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, dessen Veröffentlichung Sie aufheben möchten, unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie die Modellversion des Knotens aus, deren Veröffentlichung Sie aufheben möchten.
  5. Wählen Sie die Knoten in der Überarbeitung aus, deren Veröffentlichung Sie aufheben möchten.
  6. Wählen Sie im Drop-down-Menü Update -Optionen die Option Veröffentlichung aufheben für Knoten aus.
  7. Klicken Sie auf Aktualisieren.

Überarbeitung eines Modells aufrufen

Sie erstellen eine neue Version eines Modells, indem Sie eine neue WADL-Datei oder OpenAPI-Spezifikation in ein vorhandenes Modell importieren oder manuell eine neue Überarbeitung erstellen. Nach dem Erstellen der neuen Überarbeitung können Sie die Überarbeitung rendern und veröffentlichen. Sie ersetzt die aktuell veröffentlichten Drupal-Knoten.

Sie können Knoten aus mehreren Überarbeitungen gleichzeitig rendern und veröffentlichen. Wenn Sie also fünf Versionen eines Modells haben, können Sie Knoten aus einer oder allen Überarbeitungen veröffentlichen. Wenn Sie jedoch eine API in einem Modell veröffentlichen, das mit einem veröffentlichten Knoten in einem anderen Modell identisch ist, wird die Veröffentlichung der älteren Version der API aufgehoben und sie durch die Version der zuletzt veröffentlichten API ersetzt.

So rufen Sie die Version eines Modells auf:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie die Modellversion aus, die Sie ansehen möchten.
  5. Rendern und veröffentlichen Sie die Knoten wie oben beschrieben.

Knoten bearbeiten

Nachdem Sie einen Knoten gerendert haben, können Sie ihn mithilfe des Drupal-Editors bearbeiten. Sie können beispielsweise das HTTP-Verb und die Beschreibung einer API bearbeiten oder der API einen neuen Abfrage- oder Header-Parameter hinzufügen. Sie können Knoten bearbeiten, die aus einer WADL-Datei oder OpenAPI-Spezifikation erstellt wurden, oder Knoten, die manuell erstellt wurden.

Sie können auch die ursprüngliche WADL-Datei oder die OpenAPI-Spezifikation bearbeiten. Wenn Sie mit der Bearbeitung fertig sind, importieren Sie die WADL-Datei oder die OpenAPI-Spezifikation als neue Überarbeitung in das Modell und rendern und veröffentlichen Sie dann Ihre Änderungen wie oben beschrieben.

So bearbeiten Sie einen Knoten mit dem Drupal-Editor:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Gehen Sie zum Drupal-Knoten, der der API-Dokumentation entspricht, die Sie bearbeiten möchten.
  3. Wählen Sie Bearbeiten aus, um den Drupal-Editor zu verwenden.
  4. Nachdem Ihre Änderungen abgeschlossen sind, wählen Sie Methode aktualisieren aus.

Alternativ können Sie den Knoten im SmartDocs-Modell bearbeiten:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie die Modellversion aus, die Sie veröffentlichen möchten.
  5. Wählen Sie im Drop-down-Menü Vorgänge für die Methode, die Sie bearbeiten möchten, die Option Methode bearbeiten aus.

So löschen Sie einen Knoten:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie die Modellversion aus, die Sie veröffentlichen möchten.
  5. Wählen Sie für die Methode im Drop-down-Menü Vorgänge die Option Methode löschen aus.
    Achtung:Durch das Löschen des Knotens wird auch die API aus dem Modell entfernt. Wenn Sie die Veröffentlichung der API nur aufheben, damit sie vor Portalnutzern verborgen ist, aber nicht aus dem Modell löschen möchten, heben Sie die Veröffentlichung des Knotens wie oben beschrieben auf.

Das Portal verfügt über einen integrierten Bericht mit Informationen zu jedem Knoten, der von einem SmartDocs-Modell gerendert wird und nicht mehr auf gültige Methoden des Modells verweist. Sie können auf den Bericht zugreifen, indem Sie im Drupal-Menü die Option Berichte und dann den Bericht SmartDocs-Knotenstatus auswählen.

Modell exportieren und importieren

Mit SmartDocs können Sie ein vorhandenes Modell in eine Datei exportieren. Sie können beispielsweise eine Produktions- und eine Staging-Umgebung definieren. Anschließend nehmen Sie alle SmartDocs-Änderungen in der Staging-Umgebung vor. Wenn die APIs freigegeben werden sollen, exportieren Sie das Staging-Modell und importieren es in das Produktionsmodell.

Beim Importieren eines Modells wird eine neue Version des Modells erstellt. SmartDocs versucht, im Modell vorhandene APIs mit importierten APIs abzugleichen. Wenn SmartDocs eine Übereinstimmung erkennt, wird beim Import der Drupal-Knoten entsprechend der vorhandenen API aktualisiert. Wenn SmartDocs keine Übereinstimmung erkennt, wird beim Import ein neuer Drupal-Knoten für die API erstellt.

Angenommen, Sie haben ein POST API, das einem Drupal-Knoten mit der ID 91 entspricht. Anschließend importieren Sie ein Modell und SmartDocs erkennt eine Übereinstimmung einer POST API im importierten Modell mit der vorhandenen POST API. Bei allen Aktualisierungen der POST API wird dann Drupal-Knoten 91 aktualisiert. Wenn SmartDocs keine Übereinstimmung erkennt, wird ein neuer Drupal-Knoten mit einer neuen ID erstellt.

Drupal führt den Abgleich anhand der folgenden API-Eigenschaften durch:

  • internalName: Der interne Modellname.
  • httpMethod: Die HTTP-Methode der API, z. B. GET, PUT, POST oder DELETE.
  • resourcePath: Der Ressourcenpfad.
  • query params: Alle von der API verwendeten Abfrageparameter.

Wenn alle vier Merkmale einer importierten API mit einer im Modell vorhandenen API übereinstimmen, aktualisiert SmartDocs den vorhandenen Drupal-Knoten.

Das exportierte Modell wird durch ein einzelnes JSON-Objekt mit Einträgen für Ressourcen und Methoden dargestellt. Das bedeutet, dass Sie das exportierte Modell bearbeiten können, um eine Ressource oder Methode zu ändern, und das Modell dann neu importieren. Ändern Sie die folgenden Felder nicht, wenn Sie das JSON-Objekt bearbeiten:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

So exportieren Sie ein Modell:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie exportieren möchten, unter Vorgänge die Option Exportieren aus.
  4. Wählen Sie als Exportdateityp SmartDocs JSON aus.
  5. Klicken Sie auf Exportieren.
  6. Sie werden aufgefordert, die Datei auf der Festplatte zu speichern oder in einem Editor zu öffnen.

So importieren Sie ein Modell:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das Modell, das Sie importieren möchten, unter Vorgänge die Option Importieren aus.
  4. Wählen Sie im Drop-down-Menü Format auswählen die Option SmartDocs JSON aus.
  5. Wählen Sie als Uploadtyp Datei oder URL aus:
    1. Wenn Sie Datei auswählen, navigieren Sie zur JSON-Datei.
    2. Wenn Sie URL auswählen, geben Sie die URL der JSON-Datei von SmartDocs an.
  6. Klicken Sie auf Importieren, um es in das Modell zu importieren.
  7. Sie werden zur Informationsseite des Modells weitergeleitet. Dort können Sie das Modell jetzt rendern. Beachten Sie, dass durch den Import eine neue Version des Modells erstellt wird.
  8. Rendern und veröffentlichen Sie die Knoten.

SmartDocs-Vorlage bearbeiten

Die SmartDocs-Vorlage definiert, wie Ihre Drupal-Knoten auf dem Bildschirm angezeigt werden. Jedes SmartDocs-Modell kann dieselbe Standardvorlage verwenden oder Sie können die Vorlage für ein einzelnes Modell manuell anpassen.

Die SmartDocs-Vorlage enthält eine als HBR-Datei für Lenker codierte Vorlagendatei sowie CSS- und JavaScript-Dateien. Bei Lenken ist ein Großteil des Inhalts über eingebettete Ausdrücke wie &123;&123;body}} variabel gesteuert. Eine Liste der vorhandenen Handlebar-Ausdrücke finden Sie in einem Kommentar am Anfang der Datei. Informationen dazu, wie du deine Vorlagen mithilfe von Lenker anpassen kannst, findest du unter http://handlebarsjs.com.

In den folgenden Abschnitten wird beschrieben, wie Sie eine benutzerdefinierte SmartDocs-Vorlagendatei für alle neuen Modelle oder für den Import neuer APIs in ein vorhandenes Modell hochladen, die ursprüngliche SmartDocs-Standardvorlagendatei wiederherstellen und die SmartDocs-Vorlage für ein einzelnes Modell ändern.

Benutzerdefinierte SmartDocs-Vorlagendatei hochladen

Sie können eine benutzerdefinierte SmartDocs-Vorlagendatei als HBR-Datei für Lenker hochladen, um sie beim Erstellen neuer Modelle oder beim Importieren neuer APIs in ein vorhandenes Modell als Standardvorlage zu verwenden.

Wenn Sie die Standard-SmartDocs-Vorlagendatei als Ausgangspunkt für die Erstellung Ihrer benutzerdefinierten SmartDocs-Vorlagendatei verwenden möchten, können Sie hier eine Kopie herunterladen: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

So laden Sie eine benutzerdefinierte SmartDocs-Vorlagendatei hoch:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Konfiguration > SmartDocs aus.
  3. Maximieren Sie den Bereich Erweiterte Einstellungen.
  4. Klicken Sie unter „Benutzerdefinierte Methodenvorlage hochladen“ auf Datei auswählen und gehen Sie zur HBR-Datei „Handlebars“.
  5. Klicken Sie auf Hochladen.
  6. Klicken Sie auf Save configuration (Konfiguration speichern).

SmartDocs-Standardvorlagendatei wiederherstellen

Sie können die Standardvorlagendatei von SmartDocs wiederherstellen. Nach der Wiederherstellung wird die SmartDocs-Standardvorlagendatei verwendet, wenn neue Modelle erstellt oder neue APIs in ein vorhandenes Modell importiert werden.

So stellen Sie die SmartDocs-Standardvorlagendatei wieder her:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Konfiguration > SmartDocs aus.
  3. Maximieren Sie den Bereich Erweiterte Einstellungen.
  4. Klicken Sie unter „Benutzerdefinierte Methodenvorlage hochladen“ neben der benutzerdefinierten SmartDocs-Vorlagendatei auf Entfernen.
  5. Klicken Sie auf Save configuration (Konfiguration speichern).

SmartDocs-Vorlage für ein einzelnes Modell ändern

Sie können die für ein einzelnes Modell verwendete Vorlage ändern.

So ändern Sie die Vorlage für ein einzelnes Modell:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie Inhalte > SmartDocs im Verwaltungsmenü von Drupal aus.
  3. Wählen Sie für das Modell, das Sie bearbeiten möchten, unter Vorgänge die Option Einstellungen aus.
  4. Bearbeiten Sie die Vorlage im Bereich Methodenvorlage nach Bedarf.
  5. Klicken Sie auf Vorlage speichern.
  6. Gehen Sie zu einem Drupal-Knoten. Die Änderungen an der Vorlage sollten nun auf der Seite angezeigt werden.

SmartDocs-Authentifizierungstyp konfigurieren

In SmartDocs definierte APIs können entweder offen sein, d. h., für den Zugriff sind keine Authentifizierungsanmeldedaten erforderlich, oder sie sind sicher. Für eine sichere API müssen beim Aufruf der API Anmeldedaten übergeben werden.

Für eine sichere API unterstützt SmartDocs die folgenden Authentifizierungstypen:

  • Basisauthentifizierung – Übergeben Sie die Anmeldedaten für die Basisauthentifizierung als Nutzername und Passwort. Wenn Sie nicht festlegen, dass OAuth als Anmeldedatentyp verwendet werden soll, verwendet die API standardmäßig die Basisauthentifizierung.
  • OAuth 2.0: Ein Drittanbieter authentifiziert die Anmeldedaten des Nutzers, stellt sicher, dass der Nutzer bei der API autorisiert ist, und stellt dann ein Zugriffstoken aus. Wenn Sie eine SmartDocs-Anfrage an eine geschützte API senden, erstellt SmartDocs die Anfrage und sendet sie an den Dienstanbieter. Der Dienstanbieter validiert dann das Token und stellt sicher, dass es nicht abgelaufen ist.
  • Benutzerdefiniertes Token – Übergeben Sie einen Tokenwert als Header oder Abfrageparameter an die einzelnen Anfragen.

Für jede Art der Authentifizierung erstellen Sie ein Sicherheitsschema, das die Merkmale der Authentifizierung definiert. Bei der Authentifizierung mit benutzerdefiniertem Token definiert das Sicherheitsschema beispielsweise, wie das Token übergeben wird (Header, Abfrageparameter, Textparameter) und den Namen des Tokens.

Ein Sicherheitsschema ist einer bestimmten Version eines Modells zugeordnet. Wenn Sie also eine neue Version eines Modells erstellen, müssen Sie die Sicherheitsschemas für diese Überarbeitung neu definieren.

In einer WADL-Datei geben Sie mithilfe des Apigee-Tags <apigee:authentication> wie unten gezeigt an, ob eine API eine Authentifizierung erfordert:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

Wenn die API offen ist, setzen Sie das Attribut required auf false.

Beachten Sie, dass Sie den Authentifizierungstyp in der WADL-Datei nicht angeben können. Dazu bearbeiten Sie den Knoten in Drupal. Weitere Informationen zu WADL-Dateien finden Sie in der WADL-Referenz.

Auf der API-Seite in Drupal fügt SmartDocs die folgende Schaltfläche hinzu, damit Nutzer ihre Anmeldedaten für die Basisauthentifizierung angeben können:

Wenn Sie den Knoten bearbeiten, um den Authentifizierungstyp auf OAuth festzulegen, fügt SmartDocs die folgende Schaltfläche der Seite hinzu:

Für benutzerdefinierte Tokens fügt SmartDocs Folgendes hinzu:

Basisauthentifizierung konfigurieren

Wenn Sie die Basisauthentifizierung mit Ihrer API verwenden, müssen Sie nur das Tag <apigee:authentication> in der WADL-Datei angeben, die Sie zum Erstellen des Modells verwenden.

So wenden Sie die Basisauthentifizierung auf Methoden an, die aus einer anderen Quelle als einer WADL-Datei erstellt wurden:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das gewünschte Modell unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, unter Vorgänge die Option Sicherheitseinstellungen aus.
  5. Wählen Sie Sicherheitsschema hinzufügen aus.
  6. Geben Sie den Namen des Sicherheitsschemas an.
  7. Wählen Sie als Typ die Option Einfach aus.
  8. Tippe auf Senden.
  9. Bearbeiten Sie für jede Methode im Modell die Methode, um ihr Sicherheitsschema auf Ihr Basisschema festzulegen.
    1. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
    2. Wählen Sie für das gewünschte Modell unter „Vorgänge“ die Option API-Überarbeitungen aus.
    3. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, unter Vorgänge die Option Überarbeitungsdetails aus.
    4. Wählen Sie für die API, die Sie bearbeiten möchten, die Option Methode bearbeiten aus.
    5. Wählen Sie das Sicherheitsschema für die API aus.
    6. Speichern Sie die API.

OAuth 2.0-Authentifizierung konfigurieren

Sie können ein Modell so konfigurieren, dass es statt der standardmäßigen Basisauthentifizierung OAuth 2.0 in SmartDocs verwendet. OAuth wird an zwei Stellen konfiguriert:

  1. Erstellen Sie für jede Version eines Modells unter Sicherheitseinstellungen ein Sicherheitsschema für die Überarbeitung.
  2. Geben Sie die Client-ID und den Clientschlüssel für alle Versionen des Modells unter Einstellungen für das Modell an.

So aktivieren Sie OAuth:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das gewünschte Modell unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, unter Vorgänge die Option Sicherheitseinstellungen aus.
  5. Wählen Sie Sicherheitsschema hinzufügen aus.
  6. Geben Sie den Namen des Sicherheitsschemas an.
  7. Wählen Sie OAuth 2.0 als Typ aus.
  8. Legen Sie den Berechtigungstyp fest.
  9. Geben Sie die Werte in die Felder für die Autorisierungs-URL ein. Über die Autorisierungs-URL wird das Zugriffstoken abgerufen.
  10. Legen Sie für das Autorisierungsverb GET oder POST fest.
  11. Geben Sie die Access Token URL (Zugriffstoken-URL) ein. Die Zugriffstoken-URL ist die URL, die verwendet wird, um das Anfrage-Token gegen ein Zugriffstoken auszutauschen.
  12. Geben Sie den Namen des Zugriffstokens ein.
  13. Verwenden Sie In, um anzugeben, wie das Token übergeben werden soll: Header, Query oder Body.
  14. Legen Sie die OAuth-Bereiche fest.
  15. Tippe auf Senden.
  16. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  17. Wählen Sie für das Modell im Drop-down-Menü Vorgänge die Option Einstellungen aus.
  18. Geben Sie die Werte in die Felder Client-ID und Client-Secret ein.
  19. Wählen Sie Einstellungen für die Vorlagenauthentifizierung speichern aus.
  20. Bearbeiten Sie für jede Methode im Modell die Methode, um ihr Sicherheitsschema auf Ihr OAuth-Sicherheitsschema festzulegen.
    1. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
    2. Wählen Sie für das gewünschte Modell unter „Vorgänge“ die Option API-Überarbeitungen aus.
    3. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, unter Vorgänge die Option Überarbeitungsdetails aus.
    4. Wählen Sie für die API, die Sie bearbeiten möchten, die Option Methode bearbeiten aus.
    5. Wählen Sie das Sicherheitsschema für die API aus.
    6. Speichern Sie die API.

Benutzerdefinierte Tokenauthentifizierung konfigurieren

Sie können ein Modell für die Verwendung der benutzerdefinierten Tokenauthentifizierung konfigurieren.

So aktivieren Sie benutzerdefinierte Tokens:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
  3. Wählen Sie für das gewünschte Modell unter „Vorgänge“ die Option API-Überarbeitungen aus.
  4. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, unter Vorgänge die Option Sicherheitseinstellungen aus.
  5. Wählen Sie Sicherheitsschema hinzufügen aus.
  6. Geben Sie den Namen des Sicherheitsschemas an.
  7. Wählen Sie Apikey als Typ aus.
  8. Legen Sie den Parameter Name fest, der das Token enthält.
  9. Verwenden Sie In, um anzugeben, wie das Token übergeben werden soll: Header, Query oder Body.
  10. Tippe auf Senden.
  11. Bearbeiten Sie für jede Methode im Modell die Methode, um ihr Sicherheitsschema auf Ihr Tokenschema festzulegen.
    1. Wählen Sie im Verwaltungsmenü von Drupal Inhalte > SmartDocs aus.
    2. Wählen Sie für das gewünschte Modell unter „Vorgänge“ die Option API-Überarbeitungen aus.
    3. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, unter Vorgänge die Option Überarbeitungsdetails aus.
    4. Wählen Sie für die API, die Sie bearbeiten möchten, die Option Methode bearbeiten aus.
    5. Wählen Sie das Sicherheitsschema für die API aus.
    6. Speichern Sie die API.

Modell löschen

Wenn Sie ein Modell löschen (Inhalt > SmartDocs, Löschen im Feld „Vorgänge“ in Drupal), wird das Modell aus Ihrer Edge-Organisation gelöscht. Wenn also andere Portale auf das Modell verweisen, ist das Modell nicht mehr verfügbar. Weitere Informationen finden Sie unter SmartDoc-Modelle und Vorlagen.