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.
Dokument und API Verwendung des API Gateways REST API
In diesem Abschnitt beschreiben wir, wie Dokumentationsteile für die API Nutzung des API Gateways erstellt und verwaltet REST API werden.
Bevor Sie die Dokumentation eines erstellen und bearbeitenAPI, erstellen Sie zunächst denAPI. In diesem Abschnitt verwenden wir das PetStore
Themen
- Dokumentieren der API-Entität
- Dokumentieren einer RESOURCE-Entität
- Dokumentieren einer METHOD-Entität
- Dokumentieren einer QUERY_PARAMETER-Entität
- Dokumentieren einer PATH_PARAMETER-Entität
- Dokumentieren einer REQUEST_BODY-Entität
- Dokumentieren einer REQUEST_HEADER-Entität
- Dokumentieren einer RESPONSE-Entität
- Dokumentieren einer RESPONSE_HEADER-Entität
- Dokumentieren einer AUTHORIZER-Entität
- Dokumentieren einer MODEL-Entität
- Aktualisieren von Dokumentationsbausteinen
- Auflisten von Dokumentationsbausteinen
Dokumentieren der API
-Entität
Um Dokumentation für eine hinzuzufügen API, fügen Sie eine DocumentationPartRessource 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 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 Stammressource einer hinzuzufügenAPI, fügen Sie eine DocumentationPartRessource hinzu, die auf die entsprechende Ressourcenressource 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 zu erstellenAPI, fügen Sie eine DocumentationPartRessource hinzu, die auf die entsprechende Ressourcenressource 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. Beispielsweise:
{ "_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 durch einen Pfadparameter angegebene untergeordnete Ressource hinzuzufügen, fügen Sie eine DocumentationPartRessource hinzu, die für die Ressource Resource 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. Beispielsweise:
{ "_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 DocumentationPartInstanz einer RESOURCE
Entität kann von keiner ihrer untergeordneten Ressourcen vererbt werden.
Dokumentieren einer METHOD
-Entität
Um Dokumentation für eine Methode von hinzuzufügenAPI, fügen Sie eine DocumentationPartRessource hinzu, die auf die entsprechende Methodenressource 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 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 DocumentationPartRessource hinzu, die auf den QUERY_PARAMETER
Typ ausgerichtet ist und die gültigen Felder path
und enthältname
.
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 DocumentationPartRessource 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 DocumentationPartRessource 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 DocumentationPartRessource 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 DocumentationPartRessource hinzu, die auf die entsprechende MethodResponseRessource 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 DocumentationPartRessource 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. Beispielsweise:
{ "_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
Antwortheaders ist die Standarddokumentation für die Content-Type
Header aller Antworten von. API
Dokumentieren einer AUTHORIZER
-Entität
Um Dokumentation für einen API Autorisierer hinzuzufügen, fügen Sie eine DocumentationPartRessource 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. Beispielsweise:
{ "_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 DocumentationPartInstanz 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. Beispielsweise hat das Error
Modell, das API standardmäßig in every enthalten ist, 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 das exportiert API wird, überschreiben die Eigenschaften DocumentationPart
von die Werte im ursprünglichen Schema.
Um Dokumentation für ein API Modell hinzuzufügen, fügen Sie eine DocumentationPartRessource 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. Beispielsweise:
{ "_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 DocumentationPartInstanz einer MODEL
Entität kann von keiner ihrer untergeordneten Ressourcen vererbt werden.
Aktualisieren von Dokumentationsbausteinen
Um die Dokumentationsteile einer beliebigen Art von API Entitäten zu aktualisieren, reichen Sie eine PATCH Anfrage für eine DocumentationPartInstanz einer bestimmten Bauteil-ID ein, um die bestehende 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 aller Arten von API Entitäten aufzulisten, reichen Sie eine GET Anfrage für eine DocumentationPartsSammlung 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.