Dokumentieren einer API mit der API Gateway-Konsole

In diesem Abschnitt wird beschrieben, wie Sie die Dokumentationsbausteine einer API mit der API Gateway-Konsole erstellen und verwalten.

Eine Voraussetzung für das Erstellen und Bearbeiten der Dokumentation einer API ist, dass Sie die API bereits erstellt haben. In diesem Abschnitt verwenden wir die API PetStore als Beispiel. Um eine API mit der API Gateway-Konsole zu erstellen, befolgen Sie die Anweisungen in Tutorial: Erstellen einer REST-API durch Importieren eines Beispiels.

Dokumentieren der API-Entität

Um einen Dokumentationsbaustein für die Entität API hinzuzufügen, wählen Sie Resources aus der PetStore-API. Wählen Sie den Menüpunkt Aktionen → Edit API Documentation.

Wenn kein Dokumentationsbaustein für die API erstellt wurde, wird der properties-Map-Editor des Dokumentationsbausteins angezeigt. Geben Sie die folgende properties-Map im Texteditor ein und wählen Sie dann Save (Speichern), um den Dokumentationsbaustein zu erstellen.

{
  "info": {
    "description": "Your first API Gateway API.",
    "contact": {
        "name": "John Doe",
        "email": "[e-mail]"
    }
  }
}

Anmerkung

Sie müssen die properties-Zuordnung nicht als JSON-Zeichenfolge verschlüsseln. Die API Gateway-Konsole stringifiziert das JSON-Objekt für Sie.

Wenn bereits ein Dokumentationsbaustein erstellt wurde, wird zuerst der properties-Map-Viewer angezeigt, wie in der folgenden Abbildung dargestellt.

Die Auswahl von Bearbeiten führt zur Anzeige des properties-Map-Editors, wie gezeigt.

Dokumentieren einer RESOURCE-Entität

Um den Dokumentationsbaustein für die Stammressource der API hinzuzufügen oder zu bearbeiten, wählen Sie / unter der Struktur Resource und wählen Sie dann die Menüoption Aktionen → Edit Resource Documentation.

Wenn für diese Entität kein Dokumentationsbaustein erstellt wurde, wird das Fenster Documentation angezeigt. Geben Sie eine gültige properties-Map im Editor ein. Wählen Sie dann Speichern und Schließen.

{
    "description": "The PetStore's root resource."
}

Wenn bereits ein Dokumentationsbaustein für die RESOURCE-Entität definiert wurde, wird der Dokumentations-Viewer angezeigt. Wählen Sie Bearbeiten, um den Documentation-Editor zu öffnen. Ändern Sie die vorhandene properties-Map. Wählen Sie Speichern und dann Schließen.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen RESOURCE-Entitäten hinzuzufügen.

Dokumentieren einer METHOD-Entität

Um Dokumentation für eine METHOD-Entität z. B. mit der GET-Methode für die Stammressource hinzuzufügen oder zu bearbeiten, wählen Sie GET unter der /-Ressource und dann das Menüelement Aktionen → Methodendokumentation bearbeiten aus.

Geben Sie für den neuen Dokumentationsbaustein die folgende properties-Map im Documentation-Editor im Fenster Documentation ein. Wählen Sie dann Speichern und Schließen.

{
  "tags" : [ "pets" ],
  "description" : "PetStore HTML web page containing API usage information"
}

Wählen Sie für die vorhandene Dokumentation Bearbeiten aus dem Documentation-Viewer. Bearbeiten Sie den Inhalt der Dokumentation im Editor Documentation und wählen Sie Speichern. Klicken Sie auf Close.

Im Documentation Viewer können Sie auch den Dokumentationsbaustein löschen.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Methoden hinzuzufügen.

Dokumentieren einer QUERY_PARAMETER-Entität

Um einen Dokumentationsbaustein für einen Anforderungsabfrageparameter hinzuzufügen oder zu bearbeiten, wählen sie mit der GET /pets?type=...&page=...-Methode als Beispiel GET unter /pets in der Struktur Ressourcen aus. Wählen Sie Method Request im Fenster Method Execution aus. Erweitern Sie den Abschnitt URL Query String Parameters. Wählen Sie beispielsweise den Abfrageparameter page und wählen Sie das Buchsymbol, um den Documentation-Viewer oder -Editor zu öffnen.

Sie können auch Documentation unter der PetStore-API aus dem Hauptnavigationsbereich auswählen. Wählen Sie dann Query Parameter für Typ. Für die Beispiel-API "PetStore" werden die Dokumentationsbausteine für die Abfrageparameter page und type angezeigt.

Für eine API mit Abfrageparametern, die für andere Methoden definiert sind, können Sie Ihre Auswahl filtern, indem Sie den path der betroffenen Ressource für Path angeben, die gewünschte HTTP-Methode unter Methode auswählen oder den Namen des Abfrageparameters unter Name eingeben.

Wählen Sie z. B. den Abfrageparameter page. Wählen Sie Bearbeiten, um die vorhandene Dokumentation zu modifizieren. Wählen Sie Speichern, um die Änderung zu speichern.

Um einen neuen Dokumentationsbaustein für eine QUERY_PARAMETER-Entität hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Query Parameter für Type (Typ) aus. Geben Sie einen Ressourcenpfad (z. B. /pets) unter Path ein. Wählen Sie ein HTTP-Verb (z. B. GET) für Methode aus. Geben Sie eine properties-Beschreibung im Texteditor ein. Wählen Sie dann Speichern.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Anforderungsabfrageparametern hinzuzufügen.

Dokumentieren einer PATH_PARAMETER-Entität

Um Dokumentation für einen Pfadparameter hinzuzufügen oder zu bearbeiten, gehen Sie zu Method Request der Methode für die durch den Pfadparameter angegebene Ressource. Erweitern Sie den Abschnitt Request Paths. Wählen Sie das Buchsymbol für den Pfadparameter, um den Documentation-Viewer oder -Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der PetStore-API aus dem Hauptnavigationsbereich auswählen. Wählen Sie Path Parameter für Type (Typ) aus. Wählen Sie Bearbeiten für einen Pfadparameter aus der Liste aus. Ändern Sie den Inhalt und wählen Sie dann Speichern.

Um Dokumentation für einen nicht aufgeführten Pfadparameter hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Path Parameter für Typ. Geben Sie unter Path einen Ressourcenpfad an, wählen Sie unter Methode eine Methode aus und geben Sie unter Name einen Namen für den Pfadparameter ein. Fügen Sie die Eigenschaften der Dokumentation hinzu und wählen Sie Speichern.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Pfadparametern hinzuzufügen oder zu bearbeiten.

Dokumentieren einer REQUEST_HEADER-Entität

Um Dokumentation für einen Anforderungs-Header hinzuzufügen oder zu bearbeiten, gehen Sie zu Method Request der Methode mit dem Header-Parameter. Erweitern Sie den Abschnitt HTTP Request Headers. Wählen Sie das Buchsymbol für den Header, um den Documentation-Viewer oder -Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der API im Hauptnavigationsbereich wählen. Wählen Sie dann Request Header für Typ. Wählen Sie Bearbeiten für einen der aufgeführten Anforderungs-Header, um die Dokumentation zu ändern. Um Dokumentation für einen nicht aufgeführten Anforderungs-Header hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Request Header für Typ. Geben Sie unter Path einen Ressourcenpfad an. Wählen Sie eine Methode für Methode aus. Geben Sie einen Header-Namen unter Name ein. Fügen Sie dann eine properties-Map hinzu und speichern Sie diese.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Anforderungs-Headern hinzuzufügen oder zu bearbeiten.

Dokumentieren einer REQUEST_BODY-Entität

Um Dokumentation für einen Anforderungstext hinzuzufügen oder zu bearbeiten, gehen Sie zu Method Request für eine Methode. Wählen Sie das Buchsymbol für Request Body, um den Documentation-Viewer und dann den Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der API im Hauptnavigationsbereich wählen. Wählen Sie dann Request Body für Typ. Wählen Sie Bearbeiten für einen der aufgeführten Anforderungstexte, um die Dokumentation zu ändern. Um Dokumentation für einen nicht aufgeführten Anforderungstext hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Request Body für Type (Typ) aus. Geben Sie unter Path einen Ressourcenpfad an. Wählen Sie ein HTTP-Verb für Methode aus. Fügen Sie dann eine properties-Map hinzu und speichern Sie diese.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Anforderungstexten hinzuzufügen oder zu bearbeiten.

Dokumentieren einer RESPONSE-Entität

Um Dokumentation für eine Antwort hinzuzufügen oder zu bearbeiten, gehen Sie zu Method Response (Methodenantwort) einer Methode. Wählen Sie das Buchsymbol für Method Response (Methodenantwort) aus, um den Documentation (Dokumenation)-Viewer und dann den Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der API im Hauptnavigationsbereich wählen. Wählen Sie dann Response (status code) für Typ. Wählen Sie Bearbeiten für eine der aufgeführten Antworten mit einem bestimmten HTTP-Statuscode, um die Dokumentation zu ändern. Um Dokumentation für einen nicht aufgeführten Antworttext hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Response (Statuscode) für Typ aus Geben Sie unter Path einen Ressourcenpfad an. Wählen Sie ein HTTP-Verb für Methode aus. Geben Sie in Status Code einen HTTP-Statuscode ein. Fügen Sie dann die Eigenschaften des Dokumentationsbausteins hinzu und speichern Sie diese.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Antworten hinzuzufügen oder zu bearbeiten.

Dokumentieren einer RESPONSE_HEADER-Entität

Um Dokumentation für einen Antwort-Header hinzuzufügen oder zu bearbeiten, gehen Sie zu Method Response für eine Methode. Erweitern Sie einen Antwortabschnitt mit einem bestimmten HTTP-Status. Wählen Sie das Buchsymbol für einen Antwort-Header unter Response Headers für StatusCode, um den Documentation-Viewer und dann den -Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der API im Hauptnavigationsbereich wählen. Wählen Sie dann Response Header für Typ. Wählen Sie Bearbeiten für einen der aufgeführten Antwort-Header, um die Dokumentation zu ändern. Um Dokumentation für einen nicht aufgeführten Antwort-Header hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Response-Header für Typ. Geben Sie unter Path einen Ressourcenpfad an. Wählen Sie ein HTTP-Verb für Methode aus. Geben Sie in Status Code einen HTTP-Statuscode ein. Geben Sie unter Name den Namen für den Antwort-Header ein. Fügen Sie dann die Eigenschaften des Dokumentationsbausteins hinzu und speichern Sie diese.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Antwort-Headern hinzuzufügen oder zu bearbeiten.

Dokumentieren einer RESPONSE_BODY-Entität

Um Dokumentation für einen Antworttext hinzuzufügen oder zu bearbeiten, gehen Sie zu Method Response für eine Methode. Erweitern Sie den Antwortabschnitt mit einem bestimmten HTTP-Status. Wählen Sie das Buchsymbol für Response Body for StatusCode, um den Documentation-Viewer und dann den -Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der API im Hauptnavigationsbereich wählen. Wählen Sie dann Response Body für Typ. Wählen Sie Bearbeiten für einen der aufgeführten Antworttexte, um die Dokumentation zu ändern. Um Dokumentation für einen nicht aufgeführten Antworttext hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Response Body für Typ. Geben Sie unter Path einen Ressourcenpfad an. Wählen Sie ein HTTP-Verb für Methode aus. Geben Sie in Status Code einen HTTP-Statuscode ein. Fügen Sie dann die Eigenschaften des Dokumentationsbausteins hinzu und speichern Sie diese.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Antworttexten hinzuzufügen oder zu bearbeiten.

Dokumentieren einer MODEL-Entität

Das Dokumentieren einer MODEL-Entität beinhaltet das Erstellen und Verwalten von DocumentPart-Instances für das Modell sowie der properties jedes Modells. Das Modell Error, das standardmäßig in jeder API enthalten ist, verfügt z. B. über die folgende Schemadefinition:

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "Error Schema",
  "type" : "object",
  "properties" : {
    "message" : { "type" : "string" }
  }
}

Es erfordert zwei DocumentationPart-Instances, eine für das Model und die andere für dessen message-Eigenschaft:

{
  "location": {
    "type": "MODEL",
    "name": "Error"
  },
  "properties": {
    "title": "Error Schema",
    "description": "A description of the Error model"
  }
}

und

{
  "location": {
    "type": "MODEL",
    "name": "Error.message"
  },
  "properties": {
    "description": "An error message."
  }
}

Wenn die API exportiert wird, überschreiben die Eigenschaften des DocumentationPart die Werte im ursprünglichen Schema.

Um Dokumentation für ein Modell hinzuzufügen oder zu bearbeiten, gehen Sie zu Models der API im Hauptnavigationsbereich. Wählen Sie das Buchsymbol für den Namen eines der aufgeführten Modelle, um den Documentation-Viewer und dann den Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der API im Hauptnavigationsbereich wählen. Wählen Sie dann Model für Typ. Wählen Sie Bearbeiten für eines der aufgeführten Modelle, um die Dokumentation zu ändern. Um Dokumentation für ein nicht aufgeführtes Modell hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Model für Typ. Geben Sie unter Name einen Namen für das Modell ein. Fügen Sie dann die Eigenschaften des Dokumentationsbausteins hinzu und speichern Sie diese.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Modellen hinzuzufügen oder zu bearbeiten.

Dokumentieren einer AUTHORIZER-Entität

Um Dokumentation für einen Genehmiger hinzuzufügen oder zu bearbeiten, gehen Sie im Hauptnavigationsbereich zu Authorizers für die API. Wählen Sie das Buchsymbol für den aufgeführten Genehmiger aus, um den Documentation-Viewer und dann den Editor zu öffnen. Fügen Sie die Eigenschaften des Dokumentationsbausteins hinzu bzw. ändern Sie diese.

Sie können auch Documentation unter der API im Hauptnavigationsbereich wählen. Wählen Sie dann Authorizer für Typ. Wählen Sie Bearbeiten für einen der aufgeführten Genehmiger, um die Dokumentation zu ändern. Um Dokumentation für einen nicht aufgeführten Genehmiger hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Authorizer für Typ. Geben Sie unter Name einen Namen für den Genehmiger ein. Fügen Sie dann die Eigenschaften des Dokumentationsbausteins hinzu und speichern Sie diese.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Genehmigern hinzuzufügen oder zu bearbeiten.

Um einen Dokumentationsbaustein für einen Genehmiger hinzuzufügen, wählen Sie Create Documentation Part. Wählen Sie Authorizer für Typ. Geben Sie einen Wert für das gültige location-Feld von Name für den Genehmiger ein.

Fügen Sie den Dokumentationsinhalt im properties-Map-Editor hinzu und speichern Sie diesen.

Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu einem anderen Genehmiger hinzuzufügen.