Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Dokumentieren einer API mit der API Gateway-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.