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. # Dokumentation für REST APIs in API Gateway Um Kunden dabei zu helfen, Ihre API zu verstehen und zu verwenden, sollten Sie die API dokumentieren. Dazu können Sie mithilfe von API Gateway Hilfeinhalte für einzelne API-Entitäten als festen Bestandteil Ihres API-Entwicklungsprozesses hinzufügen und aktualisieren. API Gateway speichert die Quellinhalte und ermöglicht es Ihnen, verschiedene Versionen der Dokumentation zu archivieren. Sie können eine Dokumentationsversion mit einer API-Phase verknüpfen, einen Dokumentations-Snapshot zu einer bestimmten Phase in eine externe OpenAPI-Datei exportieren und die Datei zur Veröffentlichung der Dokumentation verteilen. Um Ihre API zu dokumentieren, können Sie die [API Gateway-REST-API](https://docs.aws.amazon.com/apigateway/latest/api/) aufrufen, eine der APIs verwenden [AWS SDKs](https://aws.amazon.com/developer/tools/), die [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/)for API Gateway verwenden oder die API Gateway Gateway-Konsole verwenden. Sie haben auch die Möglichkeit, die in einer externen OpenAPI-Datei definierten Dokumentationsbausteine zu importieren oder zu exportieren. Wenn Sie API-Dokumentation mit Entwicklern teilen möchten, können Sie ein Entwicklerportal verwenden. Ein Beispiel finden Sie unter [Integration ReadMe mit API Gateway, um Ihren Developer Hub auf dem neuesten Stand zu halten](https://aws.amazon.com/blogs/apn/integrating-readme-with-amazon-api-gateway-to-keep-your-developer-hub-up-to-date/), oder Im Blog [So optimieren Sie die API-Entwicklung auf Amazon API Gateway SmartBear SwaggerHub Using](https://aws.amazon.com/blogs/apn/how-to-streamline-api-development-on-amazon-api-gateway-using-smartbear-swaggerhub/) im AWS Partner Network (APN). **Topics** + [ # Darstellung der API-Dokumentation in API Gateway ](api-gateway-documenting-api-content-representation.md) + [ # Dokumentieren einer API mit der API Gateway-Konsole ](api-gateway-documenting-api-quick-start-with-console.md) + [ # Veröffentlichen der API-Dokumentation mithilfe der API Gateway-Konsole ](apigateway-documenting-api-with-console.md) + [ # Dokumentieren einer API mit der API Gateway-REST-API ](api-gateway-documenting-api-quick-start-with-restapi.md) + [ # Veröffentlichen der API-Dokumentation mithilfe der API Gateway-REST-API ](api-gateway-documenting-api-quick-start-publishing.md) + [ # Importieren einer API-Dokumentation ](api-gateway-documenting-api-quick-start-import-export.md) + [ # Zugriff auf API-Dokumentation in API Gateway steuern ](api-gateway-documenting-api-content-provision-and-consumption.md) # Darstellung der API-Dokumentation in API Gateway Eine API Gateway-API-Dokumentation besteht aus einzelnen Bestandteilen (Bausteinen), die sich auf bestimmte API-Entitäten beziehen, z. B. API, Ressource, Methode, Anforderung, Antwort, Nachrichtenparameter (z. B. Pfad, Abfrage, Header) sowie Genehmiger und Modelle. In API Gateway wird ein Dokumentationsteil durch eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource dargestellt. Die API-Dokumentation als Ganzes wird durch die [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html)Sammlung repräsentiert. Die Dokumentation einer API umfasst das Erstellen von `DocumentationPart`-Instances, das Hinzufügen dieser Instances zur `DocumentationParts`-Sammlung und die Pflege der verschiedenen Versionen der Dokumentationsbausteine, die im API-Entwicklungsprozess entstehen. **Topics** + [ ## Dokumentationsbausteine ](#api-gateway-documenting-api-content-representation-documentation-parts) + [ ## Dokumentationsversionen ](#api-gateway-documenting-api-content-representation-documentation-versions) ## Dokumentationsbausteine Eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource ist ein JSON-Objekt, das den Dokumentationsinhalt speichert, der für eine einzelne API-Entität gilt. Dazu gehören alle UTF-8-Inhalte und alle wichtigen Lokalisierungssprachen für Ihre Dokumentation. Das Feld `properties` enthält den Dokumentationsinhalt in Form einer Übersicht von Schlüssel-Wert-Paaren. Die Eigenschaft `location` identifiziert die zugehörige API-Entität. Sie, der API-Entwickler, bestimmen die Form einer Content Map. Der Wert eines Schlüssel-Wert-Paars kann eine Zeichenfolge, eine Zahl, ein boolescher Wert, ein Objekt oder ein Array sein. Die Form des `location`-Objekts hängt vom jeweiligen Entitätstyp ab. Die `DocumentationPart`-Ressource unterstützt das Vererben von Inhalten, das heißt, der Dokumentationsinhalt einer API-Entität gilt auch für die untergeordneten Elemente dieser API-Entität. Weitere Informationen zur Definition untergeordneter Entitäten und zur Vererbung von Inhalten finden Sie unter [Inherit Content from an API Entität of More General Specification](#api-gateway-documenting-api-content-inheritance). ### Lokation eines Dokumentationsbausteins Die [Location-Eigenschaft](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) einer [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instanz identifiziert eine API-Entität, für die der zugehörige Inhalt gilt. Die API-Entität kann eine API-Gateway-REST-API-Ressource sein [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), z. B. [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) oder [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). Die Entität kann auch ein Nachrichtenparameter sein, z. B. ein URL-Pfadparameter, ein Abfragezeichenfolge-Parameter, ein Anforderungs- oder Antwort-Header-Parameter, ein Anforderungs- oder Antworttext oder ein Antwortstatuscode. Um eine API-Entität anzugeben, wählen Sie für das Attribut [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) des Objekts `location` eine der folgenden Optionen: `API`, `AUTHORIZER`, `MODEL`, `RESOURCE`, `METHOD`, `PATH_PARAMETER`, `QUERY_PARAMETER`, `REQUEST_HEADER`, `REQUEST_BODY`, `RESPONSE`, `RESPONSE_HEADER` oder `RESPONSE_BODY`. Je nach `type` einer API-Entität können Sie auch andere `location`-Attribute angeben, z. B. [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) und [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode). Nicht alle diese Attribute gelten für eine bestimmte API-Entität. Zum Beispiel sind `type`, `path`, `name` und `statusCode` gültige Attribute der Entität `RESPONSE`; nur `type` und `path` sind gültige Lokationsattribute der Entität `RESOURCE`. Wenn Sie ein ungültiges Feld in der `location` eines `DocumentationPart` für eine bestimmte API-Entität angeben, führt dies zu einem Fehler. Nicht alle gültigen `location`-Felder sind erforderlich. Beispielsweise ist `type` ein gültiges und erforderliches `location`-Feld für alle API-Entitäten. Die Attribute `method`, `path` und `statusCode` hingegen sind gültige, aber keine erforderlichen Attribute für die Entität `RESPONSE`. Sofern nicht explizit angegeben, übernimmt ein gültiges `location`-Feld seinen Standardwert. Der Standardwert für `path` ist `/`, d. h. die Stammressource einer API. Der Standardwert für `method` oder `statusCode` ist `*`, d. h. jeder beliebige Methoden- bzw. Statuscodewert. ### Inhalt eines Dokumentationsbausteins Der Wert `properties` ist als JSON-Zeichenfolge kodiert. Der Wert `properties` enthält alle Informationen, die Sie auswählen, um Ihre Dokumentationsanforderungen zu erfüllen. Das folgende Beispiel zeigt eine gültige Content Map: ``` { "info": { "description": "My first API with Amazon API Gateway." }, "x-custom-info" : "My custom info, recognized by OpenAPI.", "my-info" : "My custom info not recognized by OpenAPI." } ``` Auch wenn API Gateway jede gültige JSON-Zeichenfolge als Content Map akzeptiert, werden die Inhaltsattribute als zwei Kategorien behandelt: als Attribute, die von OpenAPI erkannt werden, und als Attribute, die nicht von OpenAPI erkannt werden. Im vorherigen Beispiel werden `info`, `description` und `x-custom-info` von OpenAPI als OpenAPI-Standardobjekt, -eigenschaft oder -erweiterung erkannt. Im Gegensatz dazu ist `my-info` nicht mit der OpenAPI-Spezifikation kompatibel. API Gateway verteilt OpenAPI-kompatible Inhaltsattribute in die API-Entitätsdefinitionen von den verknüpften `DocumentationPart`-Instances. Die nicht kompatiblen Inhaltsattribute werden von API Gateway nicht in die API-Entitätsdefinitionen verteilt. Ein weiteres Beispiel, bei dem `DocumentationPart` für eine `Resource`-Entität gilt: ``` { "location" : { "type" : "RESOURCE", "path": "/pets" }, "properties" : { "summary" : "The /pets resource represents a collection of pets in PetStore.", "description": "... a child resource under the root...", } } ``` Hier sind sowohl `type` als auch `path` gültige Felder zur Identifizierung des Ziels des Typs `RESOURCE`. Für die Stammressource (`/`) können Sie das Feld `path` weglassen. ``` { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "The root resource with the default path specification." } } ``` Dies entspricht der folgenden `DocumentationPart`-Instance: ``` { "location" : { "type" : "RESOURCE", "path": "/" }, "properties" : { "description" : "The root resource with an explicit path specification" } } ``` ### Vererben von Inhalten aus einer API-Entität allgemeinerer Spezifikationen Der Standardwert eines optionalen `location`-Felds bietet eine musterhafte Beschreibung einer API-Entität. Unter Verwendung des Standardwerts im Objekt `location` können Sie eine allgemeine Beschreibung in der `properties`-Map zu einer `DocumentationPart`-Instance mit dieser Art von `location`-Muster hinzufügen. API Gateway extrahiert die entsprechenden OpenAPI-Dokumentationsattribute aus dem `DocumentationPart` der allgemeinen API-Entität und fügt sie in eine spezifische API-Entität mit den `location`-Feldern ein, die dem allgemeinen `location`-Muster entsprechen oder mit dem genauen Wert übereinstimmen, es sei denn, der betreffenden Entität ist bereits eine `DocumentationPart`-Instance zugeordnet. Dieses Verhalten wird auch als Vererbung von Inhalten aus einer API-Entität allgemeinerer Spezifikationen bezeichnet. Die Vererbung von Inhalten gilt für bestimmte API-Entitätentypen nicht. Weitere Details finden Sie in der nachfolgenden Tabelle. Wenn eine API-Entität mit mehr als einem `DocumentationPart`-Lokationsmuster übereinstimmt, übernimmt die Entität den Dokumentationsbaustein mit den "location"-Feldern der höchsten Priorität und Spezifität. Die Rangfolge ist `path` > `statusCode`. Für den Abgleich mit dem `path`-Feld wählt API Gateway die Entität mit dem spezifischsten Pfadwert. In der folgenden Tabelle wird dies mit ein paar Beispielen veranschaulicht. | Fall | `path` | `statusCode` | `name` | Anmerkungen | | --- | --- | --- | --- | --- | | 1 | /pets | \$1 | id | Die mit diesem Lokationsmuster verknüpfte Dokumentation wird von den Entitäten übernommen, die mit dem Lokationsmuster übereinstimmen. | | 2 | /pets | 200 | id | Die mit diesem Lokationsmuster verknüpfte Dokumentation wird von den Entitäten übernommen, die mit dem Lokationsmuster übereinstimmen, sofern Fall 1 und 2 abgeglichen werden, da Fall 2 spezifischer ist als Fall 1. | | 3 | /pets/petId | \$1 | id | Die mit diesem Lokationsmuster verknüpfte Dokumentation wird von den Entitäten übernommen, die mit dem Lokationsmuster übereinstimmen, wenn Fall 1, 2 und 3 abgeglichen werden, da Fall 3 eine höhere Priorität hat als Fall 2 und spezifischer ist als Fall 1. | Hier ein weiteres Beispiel für eine allgemeinere `DocumentationPart`-Instance im Vergleich zu einer spezifischeren Instance. Die folgende allgemeine Fehlermeldung `"Invalid request error"` wird in die OpenAPI-Definitionen der `400`-Fehlermeldungen eingefügt, sofern sie nicht überschrieben werden. ``` { "location" : { "type" : "RESPONSE", "statusCode": "400" }, "properties" : { "description" : "Invalid request error." }" } ``` Mit der folgenden Überschreibung verfügen die `400`-Antworten auf alle Methoden der `/pets`-Ressource stattdessen über die Beschreibung `"Invalid petId specified"`. ``` { "location" : { "type" : "RESPONSE", "path": "/pets", "statusCode": "400" }, "properties" : "{ "description" : "Invalid petId specified." }" } ``` ### Zulässige "location"-Felder für `DocumentationPart` Die folgende Tabelle zeigt die gültigen und erforderlichen Felder sowie die geltenden Standardwerte einer [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource, die einem bestimmten Typ von API-Entitäten zugeordnet ist. | API-Entität | Gültige "location"-Felder | Erforderliche "location"-Felder | Standardfeldwerte | Vererbbare Inhalte | | --- | --- | --- | --- | --- | | [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
| type | – | Nein | | [Ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
| type | Der Standardwert von path ist /. | Nein | | [Methode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | Die Standardwerte von path und method sind / bzw. \$1. | Ja, Abgleich von path nach Präfix und von method nach beliebigen Werten | | Abfrageparameter | 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
| type | Die Standardwerte von path und method sind / bzw. \$1. | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | | Anforderungstext | 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | Die Standardwerte von path und method sind / bzw. \$1. | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | | Parameter des Anforderungs-Headers | 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
| type, name | Die Standardwerte von path und method sind / bzw. \$1. | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | | Pfadparameter der Anforderung | 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
| type, name | Die Standardwerte von path und method sind / bzw. \$1. | Ja, Abgleich von path nach Präfix und von method nach exakten Werten | | Antwort | 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | Die Standardwerte von path, method und statusCode sind /, \$1 bzw. \$1. | Ja, Abgleich von path nach Präfix und von method und statusCode nach exakten Werten | | Antwort-Header | 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
| type, name | Die Standardwerte von path, method und statusCode sind /, \$1 bzw. \$1. | Ja, Abgleich von path nach Präfix und von method und statusCode nach exakten Werten | | Antworttext | 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | Die Standardwerte von path, method und statusCode sind /, \$1 bzw. \$1. | Ja, Abgleich von path nach Präfix und von method und statusCode nach exakten Werten | | [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
| type | – | Nein | | [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
| type | – | Nein | ## Dokumentationsversionen Eine Dokumentationsversion ist eine Momentaufnahme der [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Sammlung einer API und ist mit einer Versionskennung gekennzeichnet. Die Veröffentlichung der Dokumentation einer API umfasst das Erstellen einer Dokumentationsversion, deren Verknüpfung mit einer API-Stufe und das Exportieren dieser stufenspezifischen Version der API-Dokumentation in eine externe OpenAPI-Datei. In API Gateway wird ein Dokumentations-Snapshot als [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource dargestellt. Wenn Sie eine API aktualisieren, erstellen Sie neue Versionen der API. In API Gateway verwalten Sie alle Dokumentationsversionen mithilfe der [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Sammlung. # 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). # Veröffentlichen der API-Dokumentation mithilfe der API Gateway-Konsole Im folgenden Verfahren wird beschrieben, wie Sie eine Dokumentationsversion veröffentlichen. **So veröffentlichen Sie eine Dokumentationsversion mit der API Gateway-Konsole** 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation). 1. Wählen Sie **Publish documentation** (Dokumentation veröffentlichen) aus. 1. Konfigurieren der Veröffentlichung: 1. Wählen Sie für **Stufe** eine Stufe aus. 1. Geben Sie für **Version** eine Versionskennung ein, z. B. `1.0.0`. 1. (Optional) Geben Sie unter **Description (Beschreibung)** eine Beschreibung ein. 1. Wählen Sie **Publish**. Sie können nun die veröffentlichte Dokumentation herunterladen, indem Sie die Dokumentation in eine externe OpenAPI-Datei exportieren. Weitere Informationen hierzu finden Sie unter [REST-API von API Gateway importieren](api-gateway-export-api.md). # Dokumentieren einer API mit der API Gateway-REST-API In diesem Abschnitt wird beschrieben, wie Sie die Dokumentationsbausteine einer API mit der API Gateway-REST-API erstellen und verwalten. Vor dem Erstellen und Bearbeiten der Dokumentation einer API erstellen Sie zunächst die API. 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-documenting-api-quick-start-with-restapi-add-content-to-api) + [ ## Dokumentieren einer `RESOURCE`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource) + [ ## Dokumentieren einer `METHOD`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method) + [ ## Dokumentieren einer `QUERY_PARAMETER`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter) + [ ## Dokumentieren einer `PATH_PARAMETER`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter) + [ ## Dokumentieren einer `REQUEST_BODY`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body) + [ ## Dokumentieren einer `REQUEST_HEADER`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header) + [ ## Dokumentieren einer `RESPONSE`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response) + [ ## Dokumentieren einer `RESPONSE_HEADER`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header) + [ ## Dokumentieren einer `AUTHORIZER`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer) + [ ## Dokumentieren einer `MODEL`-Entität ](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model) + [ ## Aktualisieren von Dokumentationsbausteinen ](#api-gateway-documenting-api-quick-start-with-restapi-update-content) + [ ## Auflisten von Dokumentationsbausteinen ](#api-gateway-documenting-api-quick-start-with-restapi-list-parts) ## Dokumentieren der `API`-Entität Um Dokumentation für eine [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource für die API-Entität hinzu: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { ... "id": "s2e5xf", "location": { "path": null, "method": null, "name": null, "statusCode": null, "type": "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` Wenn der Dokumentationsbaustein bereits hinzugefügt wurde, wird eine `409 Conflict`-Antwort mit der Fehlermeldung `Documentation part already exists for the specified location: type 'API'."` zurückgegeben. In diesem Fall müssen Sie die Operation [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html) aufrufen. ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations" : [ { "op" : "replace", "path" : "/properties", "value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ] } ``` Bei einer erfolgreichen Antwort wird der Statuscode `200 OK` sowie eine Nutzlast mit der aktualisierten `DocumentationPart`-Instance in der Nutzlast zurückgegeben. ## Dokumentieren einer `RESOURCE`-Entität Um Dokumentation für die Root-Ressource einer API hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die auf die entsprechende [Ressourcenressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) ausgerichtet ist: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "RESOURCE", }, "properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" } }, "id": "p76vqo", "location": { "path": "/", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` Wenn kein Ressourcenpfad angegeben ist, wird davon ausgegangen, dass die Ressource die Stammressource ist. Sie können `"path": "/"` zu `properties` hinzufügen, um diese Spezifikation explizit zu machen. Um eine Dokumentation für eine untergeordnete Ressource einer API zu erstellen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die auf die entsprechende [Ressourcenressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) ausgerichtet ist: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "RESOURCE", "path" : "/pets" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" } }, "id": "qcht86", "location": { "path": "/pets", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` Um Dokumentation für eine untergeordnete Ressource hinzuzufügen, die durch einen Pfadparameter angegeben wird, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die für die [Ressourcenressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) bestimmt ist: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "RESOURCE", "path" : "/pets/{petId}" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" } }, "id": "k6fpwb", "location": { "path": "/pets/{petId}", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` **Anmerkung** Die [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instanz einer `RESOURCE` Entität kann von keiner ihrer untergeordneten Ressourcen vererbt werden. ## Dokumentieren einer `METHOD`-Entität Um Dokumentation für eine Methode einer API hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die auf die entsprechende [Methodenressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) ausgerichtet ist: ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "METHOD", "path" : "/pets", "method" : "GET" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` Wenn in der vorherigen Anforderung das Feld `location.method` nicht angegeben ist, wird davon ausgegangen, dass die `ANY`-Methode verwendet wird, dargestellt durch ein Platzhalterzeichen `*`. Um den Dokumentationsinhalt einer `METHOD`-Entität zu aktualisieren, rufen Sie den Vorgang [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html) auf, der eine neue `properties`-Zuordnung bereitstellt: ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations" : [ { "op" : "replace", "path" : "/properties", "value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ] } ``` Bei einer erfolgreichen Antwort wird der Statuscode `200 OK` sowie eine Nutzlast mit der aktualisierten `DocumentationPart`-Instance in der Nutzlast zurückgegeben. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ``` ## Dokumentieren einer `QUERY_PARAMETER`-Entität Um Dokumentation für einen Anforderungsabfrageparameter hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die auf den `QUERY_PARAMETER` Typ ausgerichtet ist und die gültigen Felder `path` und enthält`name`. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "QUERY_PARAMETER", "path" : "/pets", "method" : "GET", "name" : "page" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" } }, "id": "h9ht5w", "location": { "path": "/pets", "method": "GET", "name": "page", "statusCode": null, "type": "QUERY_PARAMETER" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` Die `properties`-Map des Dokumentationsbausteins einer `QUERY_PARAMETER`-Entität kann von einer der untergeordneten `QUERY_PARAMETER`-Entitäten übernommen werden. Wenn Sie z. B. eine `treats`-Ressource nach `/pets/{petId}` hinzufügen, die `GET`-Methode für `/pets/{petId}/treats` aktivieren und den `page`-Abfrageparameter bereitstellen, übernimmt dieser untergeordnete Abfrageparameter die `DocumentationPart`-Map des `properties` von dem gleichnamigen Abfrageparameter der `GET /pets`-Methode, es sei denn, Sie fügen explizit eine `DocumentationPart`-Ressource zum `page`-Abfrageparameter der `GET /pets/{petId}/treats`-Methode hinzu. ## Dokumentieren einer `PATH_PARAMETER`-Entität Um Dokumentation für einen Pfadparameter hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource für die `PATH_PARAMETER` Entität hinzu. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "PATH_PARAMETER", "path" : "/pets/{petId}", "method" : "*", "name" : "petId" }, "properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" } }, "id": "ckpgog", "location": { "path": "/pets/{petId}", "method": "*", "name": "petId", "statusCode": null, "type": "PATH_PARAMETER" }, "properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}" } ``` ## Dokumentieren einer `REQUEST_BODY`-Entität Um Dokumentation für einen Anforderungstext hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource für den Anfragetext hinzu. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "REQUEST_BODY", "path" : "/pets", "method" : "POST" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" } }, "id": "kgmfr1", "location": { "path": "/pets", "method": "POST", "name": null, "statusCode": null, "type": "REQUEST_BODY" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` ## Dokumentieren einer `REQUEST_HEADER`-Entität Um Dokumentation für einen Anforderungsheader hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource für den Anforderungsheader hinzu. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "REQUEST_HEADER", "path" : "/pets", "method" : "GET", "name" : "x-my-token" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" } }, "id": "h0m3uf", "location": { "path": "/pets", "method": "GET", "name": "x-my-token", "statusCode": null, "type": "REQUEST_HEADER" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` ## Dokumentieren einer `RESPONSE`-Entität Um eine Dokumentation für eine Antwort auf einen Statuscode hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die auf die entsprechende [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)Ressource ausgerichtet ist. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" } }, "id": "lattew", "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` ## Dokumentieren einer `RESPONSE_HEADER`-Entität Um Dokumentation für einen Antwort-Header hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource für den Antwort-Header hinzu. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Zum Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" } }, "id": "fev7j7", "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" } ``` Die Dokumentation dieses `Content-Type`-Antwort-Headers ist die Standarddokumentation für die `Content-Type`-Header aller Antworten der API. ## Dokumentieren einer `AUTHORIZER`-Entität Um Dokumentation für einen API-Autorisierer hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die für den angegebenen Autorisierer bestimmt ist. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "AUTHORIZER", "name" : "myAuthorizer" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" } }, "id": "pw3qw3", "location": { "path": null, "method": null, "name": "myAuthorizer", "statusCode": null, "type": "AUTHORIZER" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` **Anmerkung** Die [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instanz einer `AUTHORIZER` Entität kann von keiner ihrer untergeordneten Ressourcen vererbt werden. ## 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 API-Modell hinzuzufügen, fügen Sie eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Ressource hinzu, die auf das angegebene Modell ausgerichtet ist. ``` POST /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "location" : { "type" : "MODEL", "name" : "Pet" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` Bei Erfolg gibt die Operation eine `201 Created`-Antwort zurück, die die neu erstellte `DocumentationPart`-Instance in der Nutzlast enthält. Beispiel: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" } }, "id": "lkn4uq", "location": { "path": null, "method": null, "name": "Pet", "statusCode": null, "type": "MODEL" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` Wiederholen Sie denselben Schritt, um eine DocumentationPart Instanz für eine der Eigenschaften des Modells zu erstellen. **Anmerkung** Die [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instanz einer `MODEL` Entität kann von keiner ihrer untergeordneten Ressourcen vererbt werden. ## Aktualisieren von Dokumentationsbausteinen Um die Dokumentationsteile jeder Art von API-Entitäten zu aktualisieren, reichen Sie eine PATCH-Anfrage für eine [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instanz einer bestimmten Teil-ID ein, um die vorhandene `properties` Map durch eine neue zu ersetzen. ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations" : [ { "op" : "replace", "path" : "RESOURCE_PATH", "value" : "NEW_properties_VALUE_AS_JSON_STRING" } ] } ``` Bei einer erfolgreichen Antwort wird der Statuscode `200 OK` sowie eine Nutzlast mit der aktualisierten `DocumentationPart`-Instance in der Nutzlast zurückgegeben. Sie können mehrere Dokumentationsbausteine in einer einzigen `PATCH`-Anforderung aktualisieren. ## Auflisten von Dokumentationsbausteinen Um die Dokumentationsteile jeder Art von API-Entitäten aufzulisten, reichen Sie eine GET-Anfrage für eine [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Sammlung ein. ``` GET /restapis/restapi_id/documentation/parts HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` Bei einer erfolgreichen Antwort wird der Statuscode `200 OK` sowie eine Nutzlast mit den verfügbaren `DocumentationPart`-Instances in der Nutzlast zurückgegeben. # Veröffentlichen der API-Dokumentation mithilfe der API Gateway-REST-API Um die Dokumentation für eine API zu veröffentlichen, erstellen oder aktualisieren Sie einen Dokumentations-Snapshot bzw. rufen Sie einen Dokumentations-Snapshot ab und verknüpfen Sie diesen mit einer API-Stufe. Beim Erstellen eines Dokumentations-Snapshots können Sie ihn gleichzeitig mit einer eine API-Stufe verknüpfen. **Topics** + [ ## Erstellen eines Dokumentations-Snapshots und dessen Verknüpfen mit einer API-Stufe ](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage) + [ ## Erstellen eines Dokumentations-Snapshots ](#api-gateway-documenting-api-publishing-create-documentation-version) + [ ## Aktualisieren eines Dokumentations-Snapshots ](#api-gateway-documenting-api-publishing-update-documentation-version) + [ ## Abrufen eines Dokumentations-Snapshots ](#api-gateway-documenting-api-publishing-get-documentation-version) + [ ## Verknüpfen eines Dokumentations-Snapshots mit einer API-Stufe ](#api-gateway-documenting-api-publishing-stage-association) + [ ## Herunterladen eines mit einer Stufe verknüpften Dokumentations-Snapshots ](#api-gateway-documenting-api-publishing-export-documentation-version) ## Erstellen eines Dokumentations-Snapshots und dessen Verknüpfen mit einer API-Stufe Um einen Snapshot der API-Dokumentationsbausteine zu erstellen und ihn zugleich mit einer API-Stufe zu verknüpfen, übermitteln Sie die folgende `POST`-Anforderung: ``` POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "documentationVersion" : "1.0.0", "stageName": "prod", "description" : "My API Documentation v1.0.0" } ``` Bei Erfolg gibt die Operation eine `200 OK`-Antwort zurück, die die neu erstellte `DocumentationVersion`-Instance als Nutzlast enthält. Sie können auch einen Dokumentations-Snapshot erstellen, ohne ihn einer API-Stufe zuzuweisen, und dann [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) aufrufen, um den Snapshot mit einer bestimmten API-Stufe zu verknüpfen. Sie können auch einen vorhandene Dokumentations-Snapshot aktualisieren oder abfragen und dann dessen Verknüpfung ändern. Diese Schritte werden in den nächsten vier Abschnitten gezeigt. ## Erstellen eines Dokumentations-Snapshots Um einen Snapshot der Dokumentationsteile einer API zu erstellen, erstellen Sie eine neue [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource und fügen Sie sie der [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Sammlung der API hinzu: ``` POST /restapis/restapi_id/documentation/versions HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "documentationVersion" : "1.0.0", "description" : "My API Documentation v1.0.0" } ``` Bei Erfolg gibt die Operation eine `200 OK`-Antwort zurück, die die neu erstellte `DocumentationVersion`-Instance als Nutzlast enthält. ## Aktualisieren eines Dokumentations-Snapshots Sie können einen Dokumentations-Snapshot nur aktualisieren, indem Sie die `description` Eigenschaft der entsprechenden [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource ändern. Im folgenden Beispiel wird gezeigt, wie Sie die Beschreibung des Dokumentations-Snapshots gemäß seiner Versionskennung, `version`, aktualisieren (z. B. `1.0.0`). ``` PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations": [{ "op": "replace", "path": "/description", "value": "My API for testing purposes." }] } ``` Bei Erfolg gibt die Operation eine `200 OK`-Antwort zurück, die die aktualisierte `DocumentationVersion`-Instance als Nutzlast enthält. ## Abrufen eines Dokumentations-Snapshots Um eine Momentaufnahme der Dokumentation zu erhalten, reichen Sie eine `GET` Anfrage für die angegebene [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)Ressource ein. Im folgenden Beispiel wird gezeigt, wie Sie einen Dokumentations-Snapshot für eine bestimmte Versionskennung (1.0.0) abrufen. ``` GET /restapis//documentation/versions/1.0.0 HTTP/1.1 Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` ## Verknüpfen eines Dokumentations-Snapshots mit einer API-Stufe Um die API-Dokumentation zu veröffentlichen, verknüpfen Sie einen Dokumentations-Snapshot mit einer API-Stufe. Sie müssen bereits eine API-Stufe erstellt haben, bevor Sie die Dokumentationsversion damit verknüpfen können. Um einen Dokumentations-Snapshot mit einer API-Stufe über die [API Gateway-REST-API](https://docs.aws.amazon.com/apigateway/latest/api/) zu verknüpfen, rufen Sie den Vorgang [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) auf, um die gewünschte Dokumentationsversion für die Eigenschaft `stage.documentationVersion` festzulegen: ``` PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "patchOperations": [{ "op": "replace", "path": "/documentationVersion", "value": "VERSION_IDENTIFIER" }] } ``` ## Herunterladen eines mit einer Stufe verknüpften Dokumentations-Snapshots Nachdem eine Version der Dokumentationsteile einer Phase zugeordnet wurde, können Sie die Dokumentationsteile zusammen mit den API-Entitätsdefinitionen in eine externe Datei exportieren, indem Sie die API Gateway-Konsole, die API Gateway Gateway-REST-API SDKs, eine davon oder die AWS CLI für API Gateway verwenden. Der Vorgang ist mit dem für das Exportieren der API identisch. Das exportierte Dateiformat kann JSON oder YAML sein. Mit der API Gateway-REST-API können Sie auch explizit den Abfrageparameter `extension=documentation,integrations,authorizers` so konfigurieren, dass die API-Dokumentationsbausteine, API-Integrationen und Genehmiger beim API-Export berücksichtigt werden. Standardmäßig sind die Dokumentationsbausteine enthalten, die Integrationen und Genehmiger aber vom Export einer API ausgeschlossen. Die Standardausgabe von einem API-Export eignet sich für die Verteilung der Dokumentation. Um die API-Dokumentation in eine externe JSON-OpenAPI-Datei mit der API Gateway-REST-API zu exportieren, übermitteln Sie die folgende `GET`-Anforderung: ``` GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1 Accept: application/json Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` Hier enthält das Objekt `x-amazon-apigateway-documentation` die Dokumentationsbausteine und die API-Entitätsdefinitionen beinhalten die von OpenAPI unterstützten Dokumentationseigenschaften. Die Ausgabe enthält keine Details zur Integration oder zu Lambda-Genehmigern (ehemals als benutzerdefinierte Genehmiger bezeichnet). Um beide Details einzuschließen, konfigurieren Sie `extensions=integrations,authorizers,documentation`. Um Details zu Integrationen, aber nicht zu Genehmigern einzuschließen, konfigurieren Sie `extensions=integrations,documentation`. Sie müssen den `Accept:application/json`-Header in der Anforderung so konfigurieren, dass die Ausgabe in einer JSON-Datei erfolgt. Um eine YAML-Ausgabe zu erzeugen, ändern den Header der Anforderung in `Accept:application/yaml`. Als Beispiel wird eine API verwendet, die eine einfache `GET`-Methode für die Stammressource (`/`) bereitstellt. Diese API verfügt über vier API-Entitäten, die in einer OpenAPI-Definitionsdatei definiert sind, eine für jeden der Typen `API`, `MODEL`, `METHOD` und `RESPONSE`. Jeder der `API`-, `METHOD`- und `RESPONSE`-Entitäten wurde ein Dokumentationsbaustein hinzugefügt. Durch Aufrufen des vorherigen Befehls zum Exportieren der Dokumentation erhalten wir die folgende Ausgabe, wobei die Dokumentationsbausteine im Objekt `x-amazon-apigateway-documentation` als Erweiterung einer OpenAPI-Standarddatei aufgeführt werden. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "description": "API info description", "version": "2016-11-22T22:39:14Z", "title": "doc", "x-bar": "API info x-bar" }, "paths": { "/": { "get": { "description": "Method description.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } }, "x-example": "x- Method example" }, "x-bar": "resource x-bar" } }, "x-amazon-apigateway-documentation": { "version": "1.0.0", "createdDate": "2016-11-22T22:41:40Z", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "foo": "API foo", "x-bar": "API x-bar", "info": { "description": "API info description", "version": "API info version", "foo": "API info foo", "x-bar": "API info x-bar" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description.", "x-example": "x- Method example", "foo": "Method foo", "info": { "version": "method info version", "description": "method info description", "foo": "method info foo" } } }, { "location": { "type": "RESOURCE" }, "properties": { "description": "resource description", "foo": "resource foo", "x-bar": "resource x-bar", "info": { "description": "resource info description", "version": "resource info version", "foo": "resource info foo", "x-bar": "resource info x-bar" } } } ] }, "x-bar": "API x-bar", "servers": [ { "url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/test" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger" : "2.0", "info" : { "description" : "API info description", "version" : "2016-11-22T22:39:14Z", "title" : "doc", "x-bar" : "API info x-bar" }, "host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com", "basePath" : "/test", "schemes" : [ "https" ], "paths" : { "/" : { "get" : { "description" : "Method description.", "produces" : [ "application/json" ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/Empty" } } }, "x-example" : "x- Method example" }, "x-bar" : "resource x-bar" } }, "definitions" : { "Empty" : { "type" : "object", "title" : "Empty Schema" } }, "x-amazon-apigateway-documentation" : { "version" : "1.0.0", "createdDate" : "2016-11-22T22:41:40Z", "documentationParts" : [ { "location" : { "type" : "API" }, "properties" : { "description" : "API description", "foo" : "API foo", "x-bar" : "API x-bar", "info" : { "description" : "API info description", "version" : "API info version", "foo" : "API info foo", "x-bar" : "API info x-bar" } } }, { "location" : { "type" : "METHOD", "method" : "GET" }, "properties" : { "description" : "Method description.", "x-example" : "x- Method example", "foo" : "Method foo", "info" : { "version" : "method info version", "description" : "method info description", "foo" : "method info foo" } } }, { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "resource description", "foo" : "resource foo", "x-bar" : "resource x-bar", "info" : { "description" : "resource info description", "version" : "resource info version", "foo" : "resource info foo", "x-bar" : "resource info x-bar" } } } ] }, "x-bar" : "API x-bar" } ``` ------ Bei einem OpenAPI-kompatiblen Attribut, das in der `properties`-Map eines Dokumentationsbausteins definiert ist, fügt API Gateway das Attribut in die zugehörige API-Entitätsdefinition ein. Das Attribut `x-something` ist eine OpenAPI-Standarderweiterung. Diese Erweiterung wird in die API-Entitätsdefinition propagiert. Schauen Sie sich z. B. das Attribut `x-example` für die `GET`-Methode an. Ein Attribut wie `foo` ist nicht Teil der OpenAPI-Spezifikation und wird nicht in die dazugehörigen API-Entitätsdefinitionen eingefügt. Wenn ein Dokumentations-Rendering-Tool (z. B. [OpenAPI UI](https://swagger.io/tools/swagger-ui/)) die API-Entitätsdefinitionen analysiert, um Dokumentationsattribute zu extrahieren, sind alle nicht mit OpenAPI kompatiblen `properties`-Attribute einer `DocumentationPart`-Instance nicht für das Tool verfügbar. Wenn jedoch ein Dokumentations-Rendering-Tool das Objekt `x-amazon-apigateway-documentation` analysiert, um Inhalte zu erhalten, oder wenn das Tool [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) und [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) aufruft, um Dokumentationsbausteine von API Gateway abzurufen, sind alle Dokumentationsattribute für das Tool zur Anzeige verfügbar. Um die Dokumentation mit API-Entitätsdefinitionen, die Integrationsdetails enthalten, in eine JSON-OpenAPI-Datei zu exportieren, übermitteln Sie folgende `GET`-Anforderung: ``` GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1 Accept: application/json Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` Um die Dokumentation mit API-Entitätsdefinitionen, die Details zu Integrationen und Genehmigern enthalten, in eine YAML-OpenAPI-Datei zu exportieren, übermitteln Sie die folgende `GET`-Anforderung: ``` GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1 Accept: application/yaml Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret ``` Um die API Gateway-Konsole zum Exportieren und Herunterladen der veröffentlichten Dokumentation einer API zu verwenden, befolgen Sie die Anweisungen unter [REST-API über die API-Gateway-Konsole exportieren](api-gateway-export-api.md#api-gateway-export-api-from-console). # Importieren einer API-Dokumentation Wie beim Importieren von API-Entitätsdefinitionen können Sie Dokumentationsbausteine von einer externen OpenAPI-Datei in eine API in API Gateway importieren. Sie geben die to-be-imported Dokumentationsteile innerhalb der [x-amazon-apigateway-documentation Objekt](api-gateway-swagger-extensions-documentation.md) Erweiterung in einer gültigen OpenAPI-Definitionsdatei an. Durch das Importieren der Dokumentation werden die vorhandenen API-Entitätsdefinitionen nicht geändert. Sie haben die Möglichkeit, die neu angegebenen Dokumentationsbausteine in vorhandene Dokumentationsbausteine in API Gateway zusammenzuführen oder die vorhandenen Dokumentationsbausteine zu überschreiben. Im `MERGE`-Modus wird ein neuer Dokumentationsbaustein, der in der OpenAPI-Datei definiert ist, der `DocumentationParts`-Sammlung der API hinzugefügt. Wenn bereits ein importierter `DocumentationPart` vorhanden ist, ersetzt ein importiertes Attribut jeweils einen vorhandenen Baustein, sofern einer der beiden unterschiedlich ist. Andere vorhandene Dokumentationsattribute bleiben davon unberührt. Im Modus `OVERWRITE` wird die gesamte `DocumentationParts`-Sammlung entsprechend der importierten OpenAPI-Definitionsdatei ersetzt. ## Importieren der Dokumentationsbausteine mit der API Gateway-REST-API Um eine API-Dokumentation mit der API Gateway-REST-API zu importieren, rufen Sie den Vorgang [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html) auf. Das folgende Beispiel zeigt, wie vorhandene Dokumentationsbausteine einer API mit einer einzigen `GET / `-Methode überschrieben werden. Bei Erfolg wird eine `200 OK`-Antwort zurückgegeben. ------ #### [ OpenAPI 3.0 ] ``` PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "openapi": "3.0.0", "info": { "description": "description", "version": "1", "title": "doc" }, "paths": { "/": { "get": { "description": "Method description.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } } } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] }, "servers": [ { "url": "/" } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "swagger": "2.0", "info": { "description": "description", "version": "1", "title": "doc" }, "host": "", "basePath": "/", "schemes": [ "https" ], "paths": { "/": { "get": { "description": "Method description.", "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] } } ``` ------ Bei Erfolg gibt diese Anforderung eine "200 OK"-Antwort zurück, die die importierte `DocumentationPartId` in der Nutzlast enthält. ``` { "ids": [ "kg3mth", "796rtf", "zhek4p", "5ukm9s" ] } ``` Sie können auch [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) oder [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html) aufrufen. Die Dokumentationsbausteine im Objekt `x-amazon-apigateway-documentation` werden dann als Teil der OpenAPI-Eingabedatei der API-Definition bereitgestellt. Um die Dokumentationsbausteine vom API-Import auszuschließen, konfigurieren Sie `ignore=documentation` in den Abfrageparametern der Anforderung. ## Importieren der Dokumentationsbausteine mit der API Gateway-Konsole In den folgenden Anweisungen wird beschrieben, wie Sie Dokumentationsbausteine importieren. **So verwenden Sie die Konsole, um Dokumentationsbausteine einer API aus einer externen Datei zu importieren** 1. Klicken Sie im Hauptnavigationsbereich auf **Documentation** (Dokumentation). 1. Wählen Sie **Importieren** aus. 1. Wenn Sie bereits über eine Dokumentation verfügen, wählen Sie **Overwrite** (Überschreiben) oder **Merge** (Zusammenführen) aus, um Ihre neue Dokumentation entweder zu überschreiben oder zusammenzuführen. 1. Wählen Sie **Choose file** (Datei auswählen) aus, um eine Datei von einem Laufwerk zu laden, oder geben Sie die Inhalte einer Datei in die Dateiansicht ein. Ein Beispiel finden Sie in der Nutzlast der Beispielanforderung unter [Importieren der Dokumentationsbausteine mit der API Gateway-REST-API](#api-gateway-importing-api-with-swagger-file-using-rest-api). 1. Wählen Sie aus, wie mit Warnungen beim Import umgegangen werden soll. Wählen Sie entweder **Fail on warnings** (Bei Warnungen fehlschlagen) oder **Ignore warnings** (Warnungen ignorieren). Weitere Informationen finden Sie unter [Fehler und Warnungen beim Import Ihrer API in API Gateway](api-gateway-import-api-errors-warnings.md). 1. Wählen Sie **Importieren** aus. # Zugriff auf API-Dokumentation in API Gateway steuern Wenn Sie über ein eigenes Dokumentationsteam verfügen, das Ihre API-Dokumentation verfasst und bearbeitet, können Sie separate Zugriffsberechtigungen für Ihre Entwickler (für die API-Entwicklung) und für Ihre Autoren und Editoren (für die Entwicklung von Inhalten) konfigurieren. Dies ist besonders dann sinnvoll, wenn ein Drittanbieter an der Erstellung der Dokumentation beteiligt ist. Um Ihrem Dokumentationsteam Zugriff auf die Erstellung, Aktualisierung und Veröffentlichung Ihrer API-Dokumentation zu gewähren, können Sie dem Dokumentationsteam eine IAM-Rolle mit der folgenden IAM-Richtlinie zuweisen, wobei die AWS Konto-ID Ihres Dokumentationsteams angegeben *account\$1id* ist. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "StmtDocPartsAddEditViewDelete", "Effect": "Allow", "Action": [ "apigateway:GET", "apigateway:PUT", "apigateway:POST", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1:111111111111:/restapis/*/documentation/*" ] } ] } ``` ------ Weitere Informationen zum Konfigurieren von Berechtigungen für den Zugriff auf API Gateway-Ressourcen finden Sie unter [Funktionsweise von Amazon API Gateway mit IAM](security_iam_service-with-iam.md).