Dokument und API Verwendung des API Gateways REST API - APIAmazon-Gateway
Dokumentieren der API-EntitätDokumentieren einer RESOURCE-EntitätDokumentieren einer METHOD-EntitätDokumentieren einer QUERY_PARAMETER-EntitätDokumentieren einer PATH_PARAMETER-EntitätDokumentieren einer REQUEST_BODY-EntitätDokumentieren einer REQUEST_HEADER-EntitätDokumentieren einer RESPONSE-EntitätDokumentieren einer RESPONSE_HEADER-EntitätDokumentieren einer AUTHORIZER-EntitätDokumentieren einer MODEL-EntitätAktualisieren von DokumentationsbausteinenAuflisten von Dokumentationsbausteinen

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 PetStoreAPIals Beispiel. Folgen Sie den Anweisungen unter, um eine API mithilfe der API Gateway-Konsole zu erstellenTutorial: Erstellen einer REST-API durch Importieren eines Beispiels.

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.