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

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).

2. 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": "[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.

3. 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).

2. 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:

1. Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.

2. 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).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Resource (Ressource) aus.

3. Geben Sie für Path (Pfad) einen Pfad ein.

4. Geben Sie eine Beschreibung im Texteditor ein, zum Beispiel:

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

5. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für eine nicht aufgeführte Ressource erstellen.

6. 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).

2. 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:

1. Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.

2. 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).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Method (Methode) aus.

3. Geben Sie für Path (Pfad) einen Pfad ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie eine Beschreibung im Texteditor ein, zum Beispiel:

   {
     "tags" : [ "pets" ],
     "summary" : "List all pets"
   }

6. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für eine nicht aufgeführte Methode erstellen.

7. 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).

2. 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:

1. Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Resources and methods (Ressourcen und Methoden) aus.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Query parameter (Abfrageparameter) aus.

3. Geben Sie für Path (Pfad) einen Pfad ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie unter Name einen Namen ein.

6. Geben Sie eine Beschreibung im Texteditor ein.

7. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführte Abfrageparameter erstellen.

8. 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.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Path parameter (Pfadparameter) aus.

3. Geben Sie für Path (Pfad) einen Pfad ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie unter Name einen Namen ein.

6. Geben Sie eine Beschreibung im Texteditor ein.

7. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführte Pfadparameter erstellen.

8. 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.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Request header (Anforderungsheader) aus.

3. Geben Sie unter Path (Pfad) einen Pfad für den Anforderungsheader ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie unter Name einen Namen ein.

6. Geben Sie eine Beschreibung im Texteditor ein.

7. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Header erstellen.

8. 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.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Request body (Anforderungstext) aus.

3. Geben Sie unter Path (Pfad) einen Pfad für den Anforderungstext ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie eine Beschreibung im Texteditor ein.

6. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Anforderungstext erstellen.

7. 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.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen unter Documentation type (Dokumentationstyp) die Option Response (status code) (Antwort (Statuscode)) aus.

3. Geben Sie unter Path (Pfad) einen Pfad für die Antwort ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie unter Status code (Statuscode) einen HTTP-Statuscode ein.

6. Geben Sie eine Beschreibung im Texteditor ein.

7. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antwort-Statuscode erstellen.

8. 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.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Response header (Antwortheader) aus.

3. Geben Sie unter Path (Pfad) einen Pfad für den Antwortheader ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie unter Status code (Statuscode) einen HTTP-Statuscode ein.

6. Geben Sie eine Beschreibung im Texteditor ein.

7. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antwortheader erstellen.

8. 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.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Response body (Antworttext) aus.

3. Geben Sie unter Path (Pfad) einen Pfad für den Antworttext ein.

4. Wählen Sie ein HTTP-Verb für Method (Methode) aus.

5. Geben Sie unter Status code (Statuscode) einen HTTP-Statuscode ein.

6. Geben Sie eine Beschreibung im Texteditor ein.

7. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für einen nicht aufgeführten Antworttext erstellen.

8. 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.

2. 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.

3. 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:

1. Klicken Sie im Hauptnavigationsbereich auf Documentation (Dokumentation) und anschließend auf Create Documentation Part (Dokumentation erstellen).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Model (Modell) aus.

3. Geben Sie für Name einen Modellnamen ein.

4. Geben Sie eine Beschreibung im Texteditor ein.

5. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für nicht aufgeführte Modelle erstellen.

6. 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).

2. 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:

1. Wählen Sie im Bereich Documentation (Dokumentation) die Registerkarte Models (Modelle) aus.

2. 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).

2. Wählen Sie als Documentation type (Dokumentationstyp) die Option Authorizer (Genehmiger) aus.

3. Geben Sie unter Name, einen Namen für den Genehmiger ein.

4. Geben Sie eine Beschreibung im Texteditor ein. Geben Sie einen Wert für das gültige location-Feld für den Genehmiger ein.

5. Wählen Sie Create documentation part (Dokumentation erstellen) aus. Sie können Dokumentation für nicht aufgeführte Genehmiger erstellen.

6. 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.

2. Verwenden Sie die Suchleiste oder wählen Sie den Genehmiger aus und klicken Sie dann auf Edit (Bearbeiten).