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 API PetStore als Beispiel. Um eine API mit der API Gateway-Konsole zu erstellen, befolgen Sie die Anweisungen in Tutorial: Erstellen einer REST-API durch Importieren eines Beispiels.

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 API hinzuzufügen, fügen Sie eine DocumentationPart-Ressource zur 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 API hinzuzufügen, fügen Sie eine DocumentationPart-Ressource hinzu, die für die entsprechende 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",
    },
    "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 Dokumentation für eine untergeordnete Ressource einer API zu erstellen, fügen Sie eine DocumentationPart-Ressource hinzu, die für die entsprechende 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"
    },
    "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. 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/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 ist, fügen Sie eine DocumentationPart-Ressource 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. 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/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-Instance einer RESOURCE-Entität kann von keiner ihrer untergeordneten Ressourcen geerbt werden.

Dokumentieren einer `METHOD`-Entität

Um Dokumentation für eine Methode einer API hinzuzufügen, fügen Sie eine DocumentationPart-Ressource hinzu, die für die entsprechende Ressource Method 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" : "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 DocumentationPart-Ressource, die für den Typ QUERY_PARAMETER bestimmt ist, mit den gültigen Feldern path und name 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" : "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-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-Ressource für den Anforderungstext 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 Anforderungs-Header hinzuzufügen, fügen Sie eine DocumentationPart-Ressource für den Anforderungs-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" : {
         "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 Dokumentation für eine Antwort eines Statuscodes hinzuzufügen, fügen Sie eine DocumentationPart-Ressource hinzu, die für die entsprechende MethodResponse-Ressource 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": {
      "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-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-Genehmiger hinzuzufügen, fügen Sie eine DocumentationPart-Ressource hinzu, die für den angegebenen Genehmiger 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. 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/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-Instance einer AUTHORIZER-Entität kann von keiner ihrer untergeordneten Ressourcen geerbt 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-Ressource hinzu, die für das angegebene Modell 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" : "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. 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/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 diese Schritte zum Erstellen einer DocumentationPart-Instance für alle Eigenschaften des Modells.

Anmerkung

Die DocumentationPart-Instance einer MODEL-Entität kann von keiner ihrer untergeordneten Ressourcen geerbt werden.

Aktualisieren von Dokumentationsbausteinen

Um die Dokumentationsbausteine für jeden beliebigen Typ von API-Entitäten zu aktualisieren, übermitteln Sie eine PATCH-Anforderung für eine DocumentationPart-Instance einer angegebenen Bausteinkennung, um die vorhandene properties-Zuordnung 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 Dokumentationsbausteine für jeden beliebigen Typ von API-Entitäten aufzulisten, übermitteln Sie eine GET-Anforderung für eine DocumentationParts-Sammlung.


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.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Veröffentlichen der API-Dokumentation mithilfe der API Gateway-Konsole

Veröffentlichen der API-Dokumentation mithilfe der API Gateway-REST-API

Dokumentieren einer API mit der API Gateway-REST-API

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

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