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 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API 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](api-gateway-create-api-from-example.md). **Topics** + [Dokumentieren der `API`-Entität](#api-gateway-document-api-add-document-part-for-api-entity-with-console) + [Dokumentieren einer `RESOURCE`-Entität](#api-gateway-document-api-add-document-part-for-resource-entity-with-console) + [Dokumentieren einer `METHOD`-Entität](#api-gateway-document-api-add-document-part-for-method-entity-with-console) + [Dokumentieren einer `QUERY_PARAMETER`-Entität](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console) + [Dokumentieren einer `PATH_PARAMETER`-Entität](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console) + [Dokumentieren einer `REQUEST_HEADER`-Entität](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console) + [Dokumentieren einer `REQUEST_BODY`-Entität](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console) + [Dokumentieren einer `RESPONSE`-Entität](#api-gateway-document-api-add-document-part-for-response-with-console) + [Dokumentieren einer `RESPONSE_HEADER`-Entität](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console) + [Dokumentieren einer `RESPONSE_BODY`-Entität](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console) + [Dokumentieren einer `MODEL`-Entität](#api-gateway-document-api-add-document-part-for-model-entity-with-console) + [Dokumentieren einer `AUTHORIZER`-Entität](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console) ## Dokumentieren der `API`-Entität Gehen Sie wie folgt vor, um eine neue Dokumentation für die `API`-Entität hinzuzufügen: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **API** aus. Wenn kein Dokumentationsbaustein für die `API` erstellt wurde, wird der `properties`-Map-Editor des Dokumentationsbausteins angezeigt. Geben Sie die folgende `properties`-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. 1. 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: 1. Klicken Sie im Hauptnavigationsbereich auf **Resources** (Ressourcen). 1. Wählen Sie das Menü **API actions** (API-Aktionen) und dann **Update API documentation** (API-Dokumentation aktualisieren) aus. ![\[Bearbeiten der Dokumentation für die API-Entität in der API Gateway-Konsole\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png) Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Resource** (Ressource) aus. 1. Geben Sie für **Path** (Pfad) einen Pfad ein. 1. Geben Sie eine Beschreibung im Texteditor ein, zum Beispiel: ``` { "description": "The PetStore's root resource." } ``` 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für eine nicht aufgeführte Ressource erstellen. 1. 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: 1. Klicken Sie im Hauptnavigationsbereich auf **Resources** (Ressourcen). 1. Wählen Sie die Ressource aus und klicken Sie dann auf **Update documentation** (Dokumentation aktualisieren). ![\[Bearbeiten der Dokumentation für die Ressourcenentität in der API Gateway-Konsole\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png) Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Method** (Methode) aus. 1. Geben Sie für **Path** (Pfad) einen Pfad ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie eine Beschreibung im Texteditor ein, zum Beispiel: ``` { "tags" : [ "pets" ], "summary" : "List all pets" } ``` 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für eine nicht aufgeführte Methode erstellen. 1. 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: 1. Klicken Sie im Hauptnavigationsbereich auf **Resources** (Ressourcen). 1. Wählen Sie die Methode aus und klicken Sie dann auf **Update documentation** (Dokumentation aktualisieren). ![\[Bearbeiten der Dokumentation für die Methodenentität in der API Gateway-Konsole\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png) Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Query parameter** (Abfrageparameter) aus. 1. Geben Sie für **Path** (Pfad) einen Pfad ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie unter **Name** einen Namen ein. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführte Abfrageparameter erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Path parameter** (Pfadparameter) aus. 1. Geben Sie für **Path** (Pfad) einen Pfad ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie unter **Name** einen Namen ein. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführte Pfadparameter erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Request header** (Anforderungsheader) aus. 1. Geben Sie unter **Path** (Pfad) einen Pfad für den Anforderungsheader ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie unter **Name** einen Namen ein. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Header erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Request body** (Anforderungstext) aus. 1. Geben Sie unter **Path** (Pfad) einen Pfad für den Anforderungstext ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Anforderungstext erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **Bearbeiten** aus. ## Dokumentieren einer `RESPONSE`-Entität Gehen Sie wie folgt vor, um eine neue Dokumentation für eine `RESPONSE`-Entität hinzuzufügen: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen unter **Documentation type** (Dokumentationstyp) die Option **Response (status code)** (Antwort (Statuscode)) aus. 1. Geben Sie unter **Path** (Pfad) einen Pfad für die Antwort ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie unter **Status code** (Statuscode) einen HTTP-Statuscode ein. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antwort-Statuscode erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Response header** (Antwortheader) aus. 1. Geben Sie unter **Path** (Pfad) einen Pfad für den Antwortheader ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie unter **Status code** (Statuscode) einen HTTP-Statuscode ein. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antwortheader erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Response body** (Antworttext) aus. 1. Geben Sie unter **Path** (Pfad) einen Pfad für den Antworttext ein. 1. Wählen Sie ein HTTP-Verb für **Method** (Methode) aus. 1. Geben Sie unter **Status code** (Statuscode) einen HTTP-Statuscode ein. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antworttext erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Resources and methods** (Ressourcen und Methoden) aus. 1. 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. 1. Wählen Sie **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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Model** (Modell) aus. 1. Geben Sie für **Name** einen Modellnamen ein. 1. Geben Sie eine Beschreibung im Texteditor ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für nicht aufgeführte Modelle erstellen. 1. 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: 1. Klicken Sie im Navigationsbereich auf **Models** (Modelle). 1. Wählen Sie das Modell aus und klicken Sie dann auf **Update documentation** (Dokumentation aktualisieren). ![\[Bearbeiten der Dokumentation für die Modellentität in der API Gateway-Konsole\]](http://docs.aws.amazon.com/de_de/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png) Gehen Sie wie folgt vor, um eine vorhandene Dokumentation zu bearbeiten: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Models** (Modelle) aus. 1. 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: 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation) und anschließend auf **Create Documentation Part** (Dokumentation erstellen). 1. Wählen Sie als **Documentation type** (Dokumentationstyp) die Option **Authorizer** (Genehmiger) aus. 1. Geben Sie unter **Name**, einen Namen für den Genehmiger ein. 1. Geben Sie eine Beschreibung im Texteditor ein. Geben Sie einen Wert für das gültige `location`-Feld für den Genehmiger ein. 1. Wählen Sie **Create documentation part** (Dokumentation erstellen) aus. Sie können Dokumentation für nicht aufgeführte Genehmiger erstellen. 1. 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: 1. Wählen Sie im Bereich **Documentation** (Dokumentation) die Registerkarte **Authorizers** (Genehmiger) aus. 1. Verwenden Sie die Suchleiste oder wählen Sie den Genehmiger aus und klicken Sie dann auf **Edit** (Bearbeiten).