APIs mit SmartDocs dokumentieren

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur Apigee X-Dokumentation. Weitere Informationen

Mit SmartDocs können Sie Ihre APIs im Entwicklerportal von Drupal 7 so dokumentieren, dass Sie Die API-Dokumentation ist vollständig interaktiv. Durch die interaktive Dokumentation haben Portalnutzer folgende Möglichkeiten:

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

Durch das Erstellen einer interaktiven Dokumentation zu Ihren APIs machen Sie es Portalnutzern leicht, APIs zu lernen, zu testen und zu bewerten.

Die Edge-Verwaltungs-API ist eine RESTful API, mit der Sie über beliebige HTTP-Client. Apigee verwendet SmartDocs, um eine interaktive Dokumentation für das Edge-Management zu erstellen. der API erstellen. Die API-Dokumentation finden Sie hier.

Beispiel für das SmartDocs-Portal

Wenn Sie SmartDocs verwenden möchten, benötigen Sie ein Apigee Developer Services-Portal. Weitere Informationen finden Sie unter Entwickler erstellen -Portal.

Klicken Sie auf der Startseite des Entwicklerportals in der oberen Navigationsleiste auf APIs, um API-Dokumentationsseite aufrufen

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

Die Hello World API wurde aus der simulierten OpenAPI für das Ziel erstellt. Spezifikation: mocktarget.yaml. 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 einer klassischen 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. Das SmartDocs für diese Ressource ist angezeigt:
  3. Klicken Sie auf Send this request (Diese 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 cURL. um den entsprechenden cURL-Aufruf anzuzeigen.

Wie Sie Ihre APIs mit SmartDocs dokumentieren

SmartDocs stellt Ihre APIs mithilfe eines Modells dar, bei dem das Modell alle Informationen zu Ihren APIs. Das Portal extrahiert Informationen zu Ihren APIs aus dem Modell, um die Dokumentationsseiten im Portal als Drupal-Knoten rendern, wobei jeder Drupal-Knoten zu einer Seite mit Dokumentation im Portal.

Die allgemeinen Schritte zur Verwendung von SmartDocs sind:

  1. Konfigurieren Sie das Drupal SmartDocs-Modul im Portal.
  2. Erstellen Sie ein SmartDocs-Modell.
  3. Dem Modell APIs aus einer WADL-Datei, OpenAPI (früher Swagger) hinzufügen oder manuell.
  4. Rendern Sie das Modell als Sammlung von Drupal-Knoten. Jeder Drupal-Knoten Informationen zu einer einzelnen API enthält. Wenn eine Ressource in Ihrer API beispielsweise sowohl ein POST- und PUT-Anforderung 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 mit Ihrer API interagieren.
  6. Bearbeiten Sie die Drupal-Knoten vor oder nach der Veröffentlichung. Sie können die Drupal-Knoten mit dem Drupal-Editor oder der ursprünglichen WADL-Datei bearbeiten oder OpenAPI-Spezifikation. Wenn Sie mit der Bearbeitung der WADL-Datei oder der OpenAPI-Spezifikation fertig sind, importieren Sie als neue Überarbeitung in das Modell zurück, dann rendern und veröffentlichen Sie Ihre Änderungen.
  7. Aktivieren Sie TLS. Da SmartDocs Anmeldedaten zur Authentifizierung an Ihre Back-End als Teil einer Anfrage an Ihre APIs verwenden, sollten Sie TLS auf Ihrem Portal aktivieren, um dass diese Anmeldedaten sicher sind. In den Produktions- und Testumgebungen des Portals Apigee stellt das TLS-Zertifikat bereit, das für https://-Anfragen erforderlich ist. Bevor Sie jedoch müssen Sie ein eigenes TLS-Zertifikat erwerben und TLS aktivieren. Weitere Informationen finden Sie unter TLS auf dem -Portal.

Informationen zu SmartDoc-Modellen und -Vorlagen

Wenn Sie ein Modell in Ihrem Portal erstellen, wird das Modell tatsächlich in Edge gespeichert. und nicht in Drupal. Ein Modell ist ein großer JSON-Block mit einem internen Namen (z. B. „my-smartdocs-api“) und definiert die Struktur einer API. Ihr Portal hingegen Rendert das Modell in HTML und stellt eine Bearbeitungsoberfläche für das Modell bereit. Alle Aktualisierungen der API im Portal werden automatisch per Push an das Quellmodell zurückgesendet.

In der Organisation gespeichert

In Drupal gespeichert

Modelle

Vorlagen

Drupal-Knoten mit Bearbeitungsfunktion

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 Es sieht so aus, als gäbe es ein eigenes Modell, aber tatsächlich verweisen sie alle auf die Quelle. modellieren. Wenn Sie die API in der Entwicklung bearbeiten, wird das Modell aktualisiert und die Änderungen werden in der Produktion angezeigt. Wenn Sie ein Modell in der Entwicklungsumgebung löschen, wird die Quelle ebenfalls gelöscht und ist in für die Produktion.

Mit Vorlagen steuern Sie das Design Ihrer SmartDocs. Handlebars und CSS-Dateien) werden mit jeder Portalinstanz gespeichert. Damit kann jedes Portal theoretisch für jedes Modell eine eigene Vorlage. Einer der Vorteile des Rendering-Frameworks ist jedoch, dass eine Standardvorlage (entweder die Apigee-Standardvorlage oder eine von Ihnen bereitgestellte Vorlage) automatisch auf jedes Modell angewendet.

Das folgende Diagramm zeigt die Beziehung zwischen Modellen und Portalen. Die grünen Pfeile zeigen an, 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 folgendermaßen vor, um das SmartDocs-Modul konfigurieren.

<ph type="x-smartling-placeholder">

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 Modules im Drupal-Verwaltungsmenü aus. Die Liste aller Die installierten Drupal-Module werden angezeigt.
  3. Aktivieren Sie das SmartDocs-Modul.
  4. Speichern Sie die Konfiguration.
  5. Wählen Sie Modules im Drupal Admin-Menü aus.
  6. Wählen Sie SmartDocs -> Berechtigungen und achten Sie darauf, dass "Verwaltungsfunktionen für das SmartDocs-Modul für „Administrator“ Rolle aktiviert ist.
  7. Wählen Sie Konfiguration > Entwicklerportal in der Drupal-Verwaltung .
  8. Legen Sie für Connection Timeout (Verbindungszeitlimit) und Request Timeout den Wert 16 fest. Sekunden.
  9. Speichern Sie die Konfiguration.
  10. Konfigurieren Sie die URL-Einstellungen: <ph type="x-smartling-placeholder">
      </ph>
    1. Wählen Sie Konfiguration > Suche und Metadaten > URL-Aliasse > Einstellungen aus.
    2. Legen Sie die Maximale Aliaslänge und die maximale Komponente Länge auf 255 fest.
    3. Maximieren Sie Zeichensetzung.
    4. Für die 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 für Nutzer in einem internen Netzwerk ohne Zugriff auf oder wenn sich ein Teil Ihrer APIs in einem privaten Netzwerk befindet, konfigurieren Sie die SmartDocs API. Proxy-URL: <ph type="x-smartling-placeholder">
      </ph>
    1. Wählen Sie Konfiguration > SmartDocs bei der Drupal Administration .
    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 liefern. Beispiel:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      Der Standardwert in diesem 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 zur Unterstützung verschiedener APIs oder fassen Sie alle Ihre APIs in einer einzigen modellieren.

Jedes Modell hat einen eindeutigen internen Namen, mit dem auch die Basis-URL der generierten Drupal-Knoten. Die URL jedes Drupal-Knotens hat folgendes 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 Löschen.
  • resourcePath: Der Ressourcenpfad.

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

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 gespeichert Struktur. Weitere Informationen finden Sie unter Informationen zu SmartDoc-Modellen und Vorlagen.

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie Inhalte > SmartDocs in der Drupal-Verwaltung .
  3. Wählen Sie oben auf der Seite Neues Modell aus.
  4. Füllen Sie die folgenden Felder aus: <ph type="x-smartling-placeholder">
      </ph>
    • Name: Der Modellname, der auf der gesamten Website angezeigt wird.
    • Interner Name: Während Sie den Namen eingeben, wird der interne Name Namen 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 den 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. Anschließend können Sie Dropdown-Menü "Operations" (Operations) aus, um:

  • Importieren Sie eine WADL-Datei, die Ihre API beschreibt, oder geben Sie die URL einer OpenAPI an. Spezifikation, die Ihre API beschreibt.
  • Dem Modell Überarbeitung hinzufügen
  • Ändern Sie die Einstellungen des Modells, einschließlich der vom modellieren.
  • 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. Diese Datei wird in der Regel von ein vorhandenes Modell exportieren, die Datei bearbeiten und dann die Aktualisierungen importieren. Weitere Informationen Siehe Modell exportieren und importieren unten.

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

WADL importieren

Nachdem Sie ein Modell erstellt haben, importieren Sie eine WADL-Datei, die Ihre API beschreibt. Jeden Wenn Sie eine WADL-Datei importieren, wird automatisch eine neue Version des Modells erstellt.

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie Inhalte > SmartDocs in der Drupal-Version Menü „Verwaltung“.
  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 WADL im Dropdown-Menü Format auswählen im SmartDocs-Importseite
  6. Wählen Sie Datei oder URL im Upload- Typ aus.
    1. Wenn Sie Datei auswählen, wechseln Sie zur WADL-Datei.
    2. Wenn Sie URL auswählen, geben Sie die URL der WADL-Datei an.
  7. Klicken Sie auf Importieren, um das Modell in das Modell zu importieren. Sie können jetzt das Modell zu rendern.
  8. Sie werden zur Informationsseite des Modells weitergeleitet. Dort können Sie modellieren.

OpenAPI importieren Spezifikation

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

OpenAPI verwendet Dateien mit JSON-Objekten, um eine API zu beschreiben. Bei jedem Import einer OpenAPI-Spezifikation erstellt haben, erstellen Sie automatisch eine neue Überarbeitung des Modells.

<ph type="x-smartling-placeholder">

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. Auswählen Inhalt > SmartDocs im Drupal-Verwaltungsmenü.
  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 im Menü Swagger JSON oder Swagger YAML Drop-down-Menü Format auswählen auf der SmartDocs-Importseite
  6. Wählen Sie im Drop-down-Menü Datei oder URL Drop-down-Menü Upload-Typ (Sie müssen URL für OpenAPI 1.2 auswählen).
    1. Wenn Sie File (Datei) auswählen, rufen Sie die OpenAPI auf. Spezifikation.
    2. Wenn Sie URL auswählen, geben Sie die URL der OpenAPI an. Spezifikation.
  7. Klicken Sie auf Importieren, um das Modell in das Modell zu importieren.
  8. Sie werden zur Informationsseite des Modells weitergeleitet. Dort können Sie modellieren.

Ressourcen manuell erstellen und Methoden

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 Modell erstellen, können Sie mit diesem Verfahren Ihre APIs bearbeiten, z. B. neue APIs hinzufügen, nachdem zu importieren.

So fügen Sie eine API manuell hinzu:

  1. Erstellen Sie eine neue Überarbeitung des Modells.

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

    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 kombiniert der Modellüberarbeitung, 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 wurde. Für die Zeichenfolge „/login“ unterstützen Sie POST für die Anmeldung und DELETE für 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 POST und eine für DELETE.

    Die Methode verwendet die Ressourcen-URL der übergeordneten Ressource. Daher werden alle Methoden mit der gleichen URLs werden in SmartDocs unter einer einzelnen Ressource definiert.

Beachten Sie folgende allgemeine Regeln:

  • Erstellen Sie für jeden eindeutigen Basispfad in Ihrer API ein anderes SmartDocs-Modell.
  • 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 einer vorhandenen Version eines Modells hinzufügen. Wenn das Modell bereits Version hinzufügen, können Sie Ihre Ressource hinzufügen. Wenn das Modell neu ist und keine Überarbeitungen hat, erstellen Sie ein neues Ü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. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, die Option Überarbeitung hinzufügen aus. unter Vorgänge.
  4. Geben Sie auf der Seite API-Überarbeitung hinzufügen die folgenden Informationen ein: <ph type="x-smartling-placeholder">
      </ph>
    • Anzeigename: Der Name der Version, wie er in den
    • Versions-ID: Eine kurze Kennung für die Version.
    • Beschreibung: Eine Beschreibung der Überarbeitung.
    • Basis-URL: Die Basis-URL aller APIs in der Überarbeitung des Modells. A Modell unterschiedliche Basis-URLs für jede Version verwenden kann. Fügen Sie beispielsweise eine Version in der Basis-URL. Für die erste Modellversion 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 die Ressourcenpfad, der mit der Basis-URL in der Modellversion kombiniert wird, um die vollständige URL zu erstellen der Ressource.

So definieren Sie eine Ressource:

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

Optional können Sie der Ressource Parameter hinzufügen, z. B. eine Vorlage, eine Abfrage und einen Header. Parameter. Alle Ressourcenparameter werden von allen für diese Ressource definierten Methoden übernommen. Wenn Sie also einen Abfrageparameter für die Ressource definieren, werden alle Methoden, die dieser Ressource hinzugefügt wurden, muss diesen Suchparameter unterstützen.

Alternativ können Sie Parameter für eine Methode definieren. Eine POST-Methode kann beispielsweise Abfrageparameter, die von einer DELETE-Methode nicht unterstützt werden. Fügen Sie daher alle Parameter methodenspezifisch ist, wenn Sie die Methode wie unten beschrieben definieren.

Die folgende Abbildung zeigt eine vorhandene SmartDocs-Seite für das Apigee Genehmigen oder Widerrufen der Developer App API, wobei jeder Parametertyp markiert ist:

Jeder Parametertyp wird durch ein JSON-Objekt definiert:

Typ

JSON-Objekt

Hinweise

Vorlage

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

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

Wert für description erscheint in einem Pop-up, wenn der Nutzer auf einer SmartDocs-Seite die Maus über die URL bewegt.

Abfrage

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

Erforderliche Abfrageparameter können weiterhin einen defaultValue angeben, jedoch oft nicht.

Für optionale Suchparameter setzen Sie required auf false und geben Sie einen Wert für defaultValue:

Header

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

In der Beschreibung können Sie HTML-Tags verwenden.

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

[
 {
  "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 Definition des Ressourcenpfads verwenden, die in „{}“ eingeschlossen ist. Legen Sie beispielsweise folgenden Pfad fest:

/login/{org_name}/{developer_email}

Auf der SmartDocs API-Seite muss der Nutzer die URL bearbeiten, um org_name und developer_email der URL anzugeben, bevor er können sie einen Antrag einreichen.

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 definiert sein. verschiedene Methoden anwenden.

Geben Sie bei der Definition der Methode alle von der Methode verwendeten Parameter an, einschließlich Abfrage und Headerparameter. Informationen zum Hinzufügen von Parametern finden Sie in der Beschreibung oben. mit einer Methode verknüpft.

Das folgende Bild zeigt eine vorhandene SmartDocs-Seite für die Apigee Create Developer API mit jeder Bereich der Seite mit dem entsprechenden Wert markiert ist, den Sie beim Definieren eines :

Im nächsten Bild ist dieselbe Seite zu sehen, allerdings ist die Beschreibung des Anfragetexts 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. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter Vorgänge die Option API aus. Überarbeitungen, um alle Überarbeitungen eines Modells anzusehen.
  4. Wählen Sie eine Überarbeitung zum Bearbeiten aus.
  5. Wählen Sie auf der Überarbeitungsseite im Drop-down-Menü für eine der folgenden Versionen die Option Methode hinzufügen aus: Ressourcen zu finden.
  6. Geben Sie auf der Seite Bearbeitungsmethode die folgenden Informationen ein: <ph type="x-smartling-placeholder">
      </ph>
    • Anzeigename: Der Name der API, der auch zum Titel der API wird. Drupal-Seite für die API.
    • Beschreibung: Beschreiben Sie die API.
    • Methode Verb: Der HTTP-Verbtyp.
    • Sicherheitsschemata: Geben Sie den Authentifizierungsmodus, falls vorhanden, für die . Weitere Informationen finden Sie unter SmartDocs-Authentifizierung konfigurieren Typ aus.
    • Inhaltstyp: Der Inhaltstyp der Anfrage und Antwort. Weitere Informationen finden Sie in der unten über die Konfiguration verschiedener Authentifizierungsmethoden.
    • 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. POSTEN und PUT verwenden einen Anfragetext. Sie können diesen Bereich verwenden, um ihn zu beschreiben. Wenn Sie diese Wert enthält, wird der Link Description (Beschreibung) unter Request Body (Anfragetext) ausgelassen. aus der generierten SmartDocs-Seite aus.
    • Beispiel für den Anfragetext (optional): Zeigen Sie ein Beispiel für einen Anfragetext. in der Regel als JSON-Objekt oder als XML. Bei den Verben POST und PUT sollte der Anfragetext Example wird im Rahmen jeder Anfrage übergeben. Nutzer der SmartDocs-Seite bearbeiten dies bevor sie eine Anfrage an die API senden. Wenn Sie diesen Wert weglassen, Der Link Wert unter Anfragetext wird im Feld SmartDocs-Seite zu erstellen.
    • Tags: Ein Array von Tags, die der API zugeordnet sind. SmartDocs nutzt Tags, um ähnliche APIs gruppieren. Sie können beispielsweise das Tag „Statistiken“ für alle APIs zu Statistiken. Sie können APIs aus verschiedenen Ressourcen unter einem einzigen Tag gruppieren. wenn sie verwenden alle dasselbe Tag.
  7. Wählen Sie Methode hinzufügen aus. Sie werden zur Modellseite weitergeleitet. Sie können jetzt Ihre Methode 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 in Drupal-Knoten. Nach dem Rendern haben Sie ein einzelnes 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 zu verbessern.

So rendern Sie ein Modell:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie rendern möchten, unter API-Überarbeitungen Betriebsabläufe.
  4. Wählen Sie die Überarbeitung aus, die Sie rendern möchten. Sie können Knoten nur aus einer einzigen Version von das Modell zu verstehen.
  5. Wählen Sie die zu rendernden Methoden aus.
  6. Wählen Sie im Menü Update (Aktualisieren) die Option Render Nodes (Knoten rendern) aus. Optionen aus.
  7. Klicken Sie auf Aktualisieren.
  8. Es wird ein Ladebildschirm angezeigt, auf dem der Fortschritt auf Ihren Knoten zu sehen ist, die gerendert werden.
    Nachdem die Knoten gerendert wurden, wird die ID des Drupal-Knotens für jede API unter dem Spalte Knotenverknüpfung des Modells. Klicken Sie auf den Link im Node Verknüpfung hinzu, um den gerenderten Knoten zu sehen.

Anstatt Knoten rendern auszuwählen,können Sie auch Rendern: und veröffentlichen Sie Knoten, um die APIs zu rendern und sofort als Drupal-Knoten zu veröffentlichen.

Knoten veröffentlichen

Ein Knoten ist für Portalnutzer erst nach seiner Veröffentlichung sichtbar. Optional können Sie während des Rendering-Prozesses Knoten veröffentlicht werden. Wenn Sie die Knoten nicht veröffentlichen, 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. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie veröffentlichen möchten, unter API-Überarbeitungen Betriebsabläufe.
  4. Wählen Sie die Überarbeitung aus, die Sie veröffentlichen möchten. Sie können nur Knoten aus einer einzelnen Version veröffentlichen des Modells.
  5. Wählen Sie die Veröffentlichungsmethoden aus.
  6. Wählen Sie die Knoten in der zu veröffentlichenden Version aus.
  7. Wählen Sie die Option Publish Nodes (Knoten veröffentlichen) aus der Liste Update (Aktualisieren) aus. Optionen aus.
  8. Klicken Sie auf Aktualisieren.
  9. Rufen Sie den Knoten auf, indem Sie unter Knotenverknüpfung die Knoten-ID auswählen. Spalte.

Standardmäßig hat die Drupal-URL zu einem veröffentlichten API-Knoten das Format http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. So legen Sie die Form der URL fest:

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

Aufgrund der Zwischenspeicherung im Portal werden Ihre Modellseiten möglicherweise nicht sofort angezeigt. nachdem sie veröffentlicht wurden. Bei Bedarf können Sie den HTML-Cache von SmartDocs manuell mithilfe der folgenden Ablauf:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie Konfiguration > SmartDocs in der Drupal-Verwaltung .
  3. Klicken Sie auf SmartDocs-Modellcaches 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 Portalnutzern

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. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, dessen Veröffentlichung Sie aufheben möchten, unter API-Überarbeitungen Betriebsabläufe.
  4. Wählen Sie die Modellversion des Knotens aus, dessen Veröffentlichung Sie aufheben möchten.
  5. Wählen Sie die Knoten in der Version aus, deren Veröffentlichung Sie aufheben möchten.
  6. Wählen Sie die Knoten Unpublish (Veröffentlichung aufheben) aus dem Feld Update (Aktualisierung) aus. Optionen aus.
  7. Klicken Sie auf Aktualisieren.

Überarbeitung eines Modells ansehen

Sie erstellen eine neue Überarbeitung eines Modells, indem Sie eine neue WADL-Datei oder eine OpenAPI-Spezifikation importieren in ein vorhandenes Modell übernehmen oder manuell eine neue Version erstellen. Nachdem Sie die neue Überarbeitung erstellt haben, können Sie die Version rendern und veröffentlichen, wodurch die derzeit veröffentlichten Drupal-Knoten ersetzt werden.

Sie können Knoten aus mehreren Versionen gleichzeitig rendern und veröffentlichen. Das heißt, wenn Sie von fünf Versionen eines Modells können Sie Knoten aus beliebigen oder allen Versionen veröffentlichen. Die Veröffentlichung Für eine API in einem Modell, die mit einem veröffentlichten Knoten eines anderen Modells identisch ist, wird die Veröffentlichung des älteren der API-Version und ersetzt sie durch die Version der zuletzt veröffentlichten API. der API erstellen.

So rufen Sie die Überarbeitung eines Modells auf:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter API-Überarbeitungen Betriebsabläufe.
  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 mit dem Drupal-Editor bearbeiten. Sie können beispielsweise das HTTP-Verb und die Beschreibung einer API oder fügen Sie der API eine neue Abfrage oder einen neuen Headerparameter hinzu. Ich können Knoten bearbeiten, die aus einer WADL-Datei oder einer OpenAPI-Spezifikation erstellt wurden, oder Knoten, die manuell.

Sie können auch die ursprüngliche WADL-Datei oder die OpenAPI-Spezifikation bearbeiten. Wenn Sie mit dem oder die OpenAPI-Spezifikation als neue Version in das Modell importieren, rendern und veröffentlichen Sie Ihre Änderungen dann 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 für die API-Dokumentation, die Sie bearbeiten.
  3. Wählen Sie Bearbeiten aus, um den Drupal-Editor zu verwenden.
  4. Nachdem Ihre Änderungen abgeschlossen sind, wählen Sie Update Method (Methode aktualisieren) aus.

Alternativ können Sie den Knoten über das SmartDocs-Modell bearbeiten:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter API-Überarbeitungen Betriebsabläufe.
  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 Methode bearbeiten die Sie bearbeiten möchten.

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ähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie aktualisieren möchten, unter API-Überarbeitungen Betriebsabläufe.
  4. Wählen Sie die Modellversion aus, die Sie veröffentlichen möchten.
  5. Wählen Sie unter Methode löschen im Drop-down-Menü Vorgänge für die Methode aus.
    Achtung:Durch das Löschen des Knotens wird auch die API aus dem Modell entfernt. Wenn Sie nur die Veröffentlichung der API aufheben möchten, damit sie für Portalnutzer nicht sichtbar ist, aber nicht löschen möchten. aus dem Modell entfernen, sollten Sie die Veröffentlichung des Knotens wie oben beschrieben aufheben.

Das Portal verfügt über einen integrierten Bericht, der Informationen zu jedem Knoten enthält, der von einem SmartDocs-Modells, die nicht mehr auf gültige Methoden des Modells verweisen. Zugriff auf den Bericht durch im Drupal-Menü die Option Berichte und dann den gewünschten Bericht mit dem Namen SmartDocs-Knotenstatus.

Modell exportieren und importieren

Mit SmartDocs können Sie ein vorhandenes Modell in eine Datei exportieren. Sie können z. B. eine für die Produktion und eine Staging-Umgebung. Anschließend nehmen Sie alle SmartDocs-Bearbeitungen im Staging- zu verbessern. Wenn Sie zur Veröffentlichung Ihrer APIs bereit sind, exportieren Sie das Staging-Modell und importieren es in das Produktionsmodell ein.

Wenn Sie ein Modell importieren, wird eine neue Version des Modells erstellt. SmartDocs versucht, vorhandene APIs im Modell mit importierten APIs. Wenn SmartDocs eine Übereinstimmung erkennt, wird Drupal durch den Import aktualisiert. Knoten, der der vorhandenen API entspricht. Wenn SmartDocs keine Übereinstimmung erkennt, wird der Import erstellt einen neuen Drupal-Knoten für die API.

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

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

  • internalName: Der Name des internen Modells.
  • httpMethod: Die HTTP-Methode der API, z. B. GET, PUT, POST oder LÖSCHEN.
  • resourcePath: Der Ressourcenpfad.
  • query params: alle Abfrageparameter, die von der API verwendet werden.

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

Das exportierte Modell wird durch ein einzelnes JSON-Objekt mit Einträgen für Ressourcen und . Das heißt, Sie können das exportierte Modell bearbeiten, um eine Ressource oder Methode zu ändern. das Modell neu zu importieren. Wenn Sie das JSON-Objekt bearbeiten, ändern Sie die folgenden Felder nicht:

  • 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. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das zu exportierende Modell Exportieren unter Vorgänge:
  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. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie importieren möchten, unter Importieren Vorgänge:
  4. Wählen Sie im Drop-down-Menü Format auswählen die Option SmartDocs-JSON aus.
  5. Wählen Sie Datei oder URL aus. Upload-Typ: <ph type="x-smartling-placeholder">
      </ph>
    1. Wenn Sie Datei auswählen, wechseln Sie zur JSON-Datei.
    2. Wenn Sie URL auswählen, geben Sie die URL der SmartDocs-JSON-Datei an.
  6. Klicken Sie auf Importieren, um das Modell in das Modell zu importieren.
  7. Sie werden zur Informationsseite des Modells weitergeleitet. Dort können Sie modellieren. Beachten Sie, dass durch den Import eine neue Version des Modells erstellt wird.
  8. Knoten rendern und veröffentlichen

SmartDocs-Vorlage bearbeiten

Die SmartDocs-Vorlage legt fest, 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 um ein individuelles Modell zu erstellen.

Die SmartDocs-Vorlage enthält eine Vorlagendatei, die als HBR-Datei für Handlebars codiert ist, CSS-Dateien, und JavaScript-Dateien. Bei Handlebars ist ein Großteil der Inhalte variabel, da eingebettete Ziehleistenausdrücke wie &123;&123;body}}. Eine Liste der vorhandenen Handlebar-Ausdrücke finden Sie in einem Kommentar am Anfang der Datei. Informationen zu wie du deine Vorlagen mithilfe von Handlebars anpassen kannst, siehe http://handlebarsjs.com.

In den folgenden Abschnitten wird beschrieben, wie Sie eine benutzerdefinierte SmartDocs-Vorlagendatei zur Verwendung durch alle neue Modelle erstellen oder neue APIs in ein vorhandenes Modell importieren, Standard-SmartDocs-Vorlagendatei und wie Sie die SmartDocs-Vorlage für eine um ein individuelles Modell zu erstellen.

Benutzerdefiniertes Element hochladen SmartDocs-Vorlagendatei

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

Wenn Sie die Standard-SmartDocs-Vorlagendatei als Ausgangspunkt beim Erstellen Ihre benutzerdefinierte SmartDocs-Vorlagendatei erstellen, 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 Konfiguration > SmartDocs in Drupal Menü „Verwaltung“.
  3. Maximiere auf der Seite den Bereich Erweiterte Einstellungen.
  4. Klicken Sie unter „Vorlage für benutzerdefinierte Methode hochladen“ auf Datei auswählen. navigieren Sie zur HBR-Datei für Handlebars.
  5. Klicken Sie auf Hochladen.
  6. Klicken Sie auf Save configuration (Konfiguration speichern).

Das Wiederherstellen des Standard-SmartDocs-Vorlagendatei

Sie können die Standard-SmartDocs-Vorlagendatei wiederherstellen. Nach der Wiederherstellung wird die Standard-SmartDocs Vorlagendatei wird beim Erstellen neuer Modelle oder beim Importieren neuer APIs in ein vorhandenes Modell verwendet. modellieren.

So stellen Sie die Standard-SmartDocs-Vorlagendatei wieder her:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wählen Sie Konfiguration > SmartDocs in Drupal Menü „Verwaltung“.
  3. Maximiere auf der Seite den Bereich Erweiterte Einstellungen.
  4. Klicken Sie unter „Vorlage für benutzerdefinierte Methode hochladen“ neben dem benutzerdefinierte SmartDocs-Vorlagendatei.
  5. Klicken Sie auf Save configuration (Konfiguration speichern).

Wird geändert der SmartDocs-Vorlage für ein einzelnes Modell

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

So ändern Sie die Vorlage für ein Einzelmodell:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Auswählen Inhalt > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das Modell, das Sie bearbeiten möchten, unter Einstellungen die Option Vorgänge:
  4. Bearbeiten Sie die Vorlage im Bereich Method Template (Methodenvorlage) nach Bedarf.
  5. Klicken Sie auf Vorlage speichern.
  6. Gehen Sie zu einem Drupal-Knoten. Die Änderungen an der Vorlage sollten jetzt auf der Seite zu sehen sein.

Das Konfigurieren der SmartDocs-Authentifizierungstyp

In SmartDocs definierte APIs können entweder offen sein, d. h., es werden keine Anmeldedaten zur Authentifizierung verwendet. die für den Zugriff erforderlich sind, oder sicher sein. Eine sichere API erfordert, dass Sie beim Erstellen einer an die API senden.

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

  • Basisauthentifizierung: Die Anmeldedaten für die Basisauthentifizierung werden als Nutzername und Passwort. Wenn Sie nicht OAuth als Anmeldedatentyp angeben, verwendet standardmäßig die Basisauthentifizierung.
  • OAuth 2.0: Ein Drittanbieter authentifiziert die Anmeldedaten, stellt sicher, dass der Nutzer für die API autorisiert ist, und gibt dann einen Zugriff aus Token. Wenn Sie eine SmartDocs-Anfrage an eine geschützte API senden, erstellt SmartDocs die Anfrage und an den Dienstanbieter sendet. Der Dienstanbieter validiert das Token und stellt sicher, dass er nicht abgelaufen ist.
  • Benutzerdefiniertes Token – Übergeben Sie an jede Methode einen Tokenwert als Header oder Abfrageparameter.

Für jeden Authentifizierungstyp erstellen Sie ein Sicherheitsschema, das die Merkmale der Authentifizierung. Für die Authentifizierung mit benutzerdefinierten Tokens ist beispielsweise Sicherheitsschema definiert, wie das Token übergeben wird (Header, query param, body param) und den Namen des das Token.

Ein Sicherheitsschema ist mit einer bestimmten Überarbeitung eines Modells verknüpft. Wenn Sie also eine neue Version eines Modells erstellt haben, müssen Sie die Sicherheitsschemas für diese Version

In einer WADL-Datei geben Sie mithilfe des Apigee-Tags &lt;apigee:authentication&gt; an, ob eine API eine Authentifizierung erfordert. (siehe unten):

<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 müssen Sie und bearbeiten den Knoten in Drupal. Weitere Informationen zu WADL-Dateien finden Sie unter WADL Referenz.

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

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

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

Wird konfiguriert Basisauthentifizierung

Wenn Sie die Basisauthentifizierung mit Ihrer API verwenden, müssen Sie nur das Tag &lt;apigee:authentication&gt; im WADL-Element angeben Datei, mit der Sie das Modell erstellen.

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ähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das gewünschte Modell unter API-Überarbeitungen Betriebsabläufe.
  4. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, die Option Sicherheit aus. Einstellungen unter Vorgänge 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. Wählen Sie Senden aus.
  9. Bearbeiten Sie für jede Methode im Modell die Methode, um das zugehörige Sicherheitsschema festzulegen. auf Ihr Grundschema anwenden.
    1. Wähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
    2. Wählen Sie für das gewünschte Modell unter API-Überarbeitungen Betriebsabläufe.
    3. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, die Option Revision Details unter Vorgänge.
    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.

Wird konfiguriert OAuth 2.0-Authentifizierung

Sie können ein Modell so konfigurieren, dass in SmartDocs OAuth 2.0 anstelle der Standardeinstellung der einfachen Version verwendet wird. Authentifizierung. OAuth wird an zwei Stellen konfiguriert:

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

So aktivieren Sie OAuth:

  1. Melden Sie sich in Ihrem Portal als Nutzer mit Administrator- oder Berechtigungen zum Erstellen von Inhalten an.
  2. Wähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
  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, Sicherheitseinstellungen aus. Vorgänge:
  5. Wählen Sie Sicherheitsschema hinzufügen aus.
  6. Geben Sie den Namen des Sicherheitsschemas an.
  7. Wählen Sie als Typ OAuth 2.0 aus.
  8. Legen Sie den Berechtigungstyp fest.
  9. Geben Sie die Werte in die Felder Autorisierungs-URL ein. Die Autorisierung Die URL wird verwendet, um das Zugriffstoken abzurufen.
  10. Lege das Autorisierungsverb auf GET oder POST fest.
  11. Geben Sie die Access Token URL (URL des Zugriffstokens) ein. Die Zugriffstoken-URL ist die URL für tauschen Sie das Anforderungs-Token gegen ein Zugriffstoken aus.
  12. Geben Sie den Namen des Zugriffstoken-Parameters ein.
  13. Verwenden Sie In, um anzugeben, wie das Token übergeben werden soll: Header, Query oder Body an.
  14. Legen Sie die OAuth-Bereiche fest.
  15. Wählen Sie Senden aus.
  16. Wähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
  17. Wählen Sie für das Modell im Bereich Operations (Vorgänge) die Option Settings (Einstellungen) aus. aus.
  18. Geben Sie die Werte in die Felder Client-ID und Client Secret:
  19. Wählen Sie Authentifizierungseinstellungen der Vorlage speichern aus.
  20. Bearbeiten Sie für jede Methode im Modell die Methode, um das zugehörige Sicherheitsschema festzulegen. mit Ihrem OAuth-Sicherheitsschema.
    1. Wähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
    2. Wählen Sie für das gewünschte Modell unter API-Überarbeitungen Betriebsabläufe.
    3. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, die Option Revision Details unter Vorgänge.
    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 so konfigurieren, dass die Authentifizierung mit benutzerdefinierten Tokens verwendet wird.

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ähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
  3. Wählen Sie für das gewünschte Modell unter API-Überarbeitungen Betriebsabläufe.
  4. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, die Option Sicherheit aus. Einstellungen unter Vorgänge aus.
  5. Wählen Sie Sicherheitsschema hinzufügen aus.
  6. Geben Sie den Namen des Sicherheitsschemas an.
  7. Wählen Sie als Typ Apikey aus.
  8. Legen Sie den Parameternamen fest, der das Token enthält.
  9. Mit In geben Sie an, wie der token: Header, Query oder Text.
  10. Wählen Sie Senden aus.
  11. Bearbeiten Sie für jede Methode im Modell die Methode, um das zugehörige Sicherheitsschema festzulegen. in Ihr Tokenschema ein.
    1. Wähle Inhalte > SmartDocs in im Administrationsmenü von Drupal.
    2. Wählen Sie für das gewünschte Modell unter API-Überarbeitungen Betriebsabläufe.
    3. Wählen Sie für die Modellversion, die Sie bearbeiten möchten, die Option Revision Details unter Vorgänge.
    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 in im Feld Vorgänge in Drupal), wird das Modell aus Ihrer Edge-Organisation gelöscht. Das heißt, wenn andere Portale auf das Modell verweisen, ist das Modell nicht mehr verfügbar. Weitere Informationen Siehe SmartDoc-Modelle und -Vorlagen