Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
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
Themen
Dokumentieren der API-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für die API-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option API aus.
Wenn kein Dokumentationsbaustein für die
APIerstellt wurde, wird derproperties-Map-Editor des Dokumentationsbausteins angezeigt. Geben Sie die folgendeproperties-Zuweisung in den Texteditor ein.{ "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } }Anmerkung
Sie müssen die
properties-Zuordnung nicht als JSON-Zeichenfolge verschlüsseln. Die API Gateway-Konsole stringifiziert das JSON-Objekt für Sie.-
Wählen Sie Create documentation part (Dokumentation erstellen) aus.
Gehen Sie wie folgt vor, um eine neue Dokumentation für die API-Entität im Bereich Resources (Ressourcen) hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Resources (Ressourcen).
Wählen Sie das Menü API actions (API-Aktionen) und dann Update API documentation (API-Dokumentation aktualisieren) aus.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Wählen Sie den Namen Ihrer API aus und klicken Sie dann auf der API-Karte auf Edit (Bearbeiten).
Dokumentieren einer RESOURCE-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine RESOURCE-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Resource (Ressource) aus.
Geben Sie für Path (Pfad) einen Pfad ein.
Geben Sie eine Beschreibung im Texteditor ein, zum Beispiel:
{ "description": "The PetStore's root resource." }Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für eine nicht aufgeführte Ressource erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine RESOURCE-Entität im Bereich Resources (Ressourcen) hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Resources (Ressourcen).
Wählen Sie die Ressource aus und klicken Sie dann auf Update documentation (Dokumentation aktualisieren).
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Wählen Sie die Ressource aus, die Ihre Dokumentation enthält, und klicken Sie dann auf Edit (Bearbeiten).
Dokumentieren einer METHOD-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine METHOD-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Method (Methode) aus.
Geben Sie für Path (Pfad) einen Pfad ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie eine Beschreibung im Texteditor ein, zum Beispiel:
{ "tags" : [ "pets" ], "summary" : "List all pets" }Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für eine nicht aufgeführte Methode erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine METHOD-Entität im Bereich Resources (Ressourcen) hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Resources (Ressourcen).
Wählen Sie die Methode aus und klicken Sie dann auf Update documentation (Dokumentation aktualisieren).
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können die Methode oder die Ressource auswählen, die die Methode enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
Dokumentieren einer QUERY_PARAMETER-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine QUERY_PARAMETER-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Query parameter (Abfrageparameter) aus.
Geben Sie für Path (Pfad) einen Pfad ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie unter Name einen Namen ein.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführte Abfrageparameter erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können den Abfrageparameter oder die Ressource auswählen, die den Abfrageparameter enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
Dokumentieren einer PATH_PARAMETER-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine PATH_PARAMETER-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Path parameter (Pfadparameter) aus.
Geben Sie für Path (Pfad) einen Pfad ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie unter Name einen Namen ein.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführte Pfadparameter erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können den Pfadparameter oder die Ressource auswählen, die den Pfadparameter enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
Dokumentieren einer REQUEST_HEADER-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine REQUEST_HEADER-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Request header (Anforderungsheader) aus.
Geben Sie unter Path (Pfad) einen Pfad für den Anforderungsheader ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie unter Name einen Namen ein.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Header erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können den Anforderungsheader oder die Ressource auswählen, die den Anforderungsheader enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
Dokumentieren einer REQUEST_BODY-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine REQUEST_BODY-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Request body (Anforderungstext) aus.
Geben Sie unter Path (Pfad) einen Pfad für den Anforderungstext ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Anforderungstext erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können den Anforderungstext oder die Ressource auswählen, die den Anforderungstext enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
Dokumentieren einer RESPONSE-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine RESPONSE-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen unter Documentation type (Dokumentationstyp) die Option Response (status code) (Antwort (Statuscode)) aus.
Geben Sie unter Path (Pfad) einen Pfad für die Antwort ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie unter Status code (Statuscode) einen HTTP-Statuscode ein.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antwort-Statuscode erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können den Antwort-Statuscode oder die Ressource auswählen, die den Antwort-Statuscode enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
Dokumentieren einer RESPONSE_HEADER-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine RESPONSE_HEADER-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Response header (Antwortheader) aus.
Geben Sie unter Path (Pfad) einen Pfad für den Antwortheader ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie unter Status code (Statuscode) einen HTTP-Statuscode ein.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antwortheader erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können den Antwortheader oder die Ressource auswählen, die den Antwortheader enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
Dokumentieren einer RESPONSE_BODY-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine RESPONSE_BODY-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Response body (Antworttext) aus.
Geben Sie unter Path (Pfad) einen Pfad für den Antworttext ein.
Wählen Sie ein HTTP-Verb für Method (Methode) aus.
Geben Sie unter Status code (Statuscode) einen HTTP-Statuscode ein.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antworttext erstellen.
Wiederholen Sie ggf. diese Schritte, um eine weitere Dokumentation hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.
Sie können den Antworttext oder die Ressource auswählen, die den Antworttext enthält, und dann mithilfe der Suchleiste die Dokumentation suchen und auswählen.
Wählen Sie Edit (Bearbeiten) aus.
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.
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine MODEL-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Model (Modell) aus.
Geben Sie für Name einen Modellnamen ein.
Geben Sie eine Beschreibung im Texteditor ein.
Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für nicht aufgeführte Modelle erstellen.
Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Modellen hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine MODEL-Entität im Bereich Models (Modelle) hinzuzufügen:
Klicken Sie im Navigationsbereich auf Models (Modelle).
Wählen Sie das Modell aus und klicken Sie dann auf Update documentation (Dokumentation aktualisieren).
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Models (Modelle) aus.
Verwenden Sie die Suchleiste oder wählen Sie das Modell aus und klicken Sie dann auf Edit (Bearbeiten).
Dokumentieren einer AUTHORIZER-Entität
Gehen Sie wie folgt vor, um eine neue Dokumentation für eine AUTHORIZER-Entität hinzuzufügen:
Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).
Wählen Sie als Documentation type (Dokumentationstyp) die Option Authorizer (Genehmiger) aus.
Geben Sie unter Name, einen Namen für den Genehmiger ein.
Geben Sie eine Beschreibung im Texteditor ein. Geben Sie einen Wert für das gültige
location-Feld für den Genehmiger ein.Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für nicht aufgeführte Genehmiger erstellen.
Wiederholen Sie ggf. diese Schritte, um einen Dokumentationsbaustein zu anderen Genehmigern hinzuzufügen oder zu bearbeiten.
Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten:
Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Authorizers (Genehmiger) aus.
Verwenden Sie die Suchleiste oder wählen Sie den Genehmiger aus und klicken Sie dann auf Edit (Bearbeiten).
