Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Dokumentasikan API menggunakan API Gateway REST API
Di bagian ini, kami menjelaskan cara membuat dan memelihara bagian dokumentasi API menggunakan API Gateway REST API.
Sebelum membuat dan mengedit dokumentasi API, buat dulu API. Pada bagian ini, kita menggunakan [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)API sebagai contoh. Untuk membuat API menggunakan konsol API Gateway, ikuti petunjuk di[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md).
**Topics**
+ [Dokumentasikan `API` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api)
+ [Dokumentasikan `RESOURCE` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource)
+ [Dokumentasikan `METHOD` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method)
+ [Dokumentasikan `QUERY_PARAMETER` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter)
+ [Dokumentasikan `PATH_PARAMETER` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter)
+ [Dokumentasikan `REQUEST_BODY` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body)
+ [Dokumentasikan `REQUEST_HEADER` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header)
+ [Dokumentasikan `RESPONSE` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response)
+ [Dokumentasikan `RESPONSE_HEADER` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header)
+ [Dokumentasikan `AUTHORIZER` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer)
+ [Dokumentasikan `MODEL` entitas](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model)
+ [Perbarui bagian dokumentasi](#api-gateway-documenting-api-quick-start-with-restapi-update-content)
+ [Daftar bagian dokumentasi](#api-gateway-documenting-api-quick-start-with-restapi-list-parts)
## Dokumentasikan `API` entitas
Untuk menambahkan dokumentasi untuk [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)resource untuk entitas API:
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
...
"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}"
}
```
Jika bagian dokumentasi telah ditambahkan, `409 Conflict` respons kembali, berisi pesan kesalahan Dalam hal ini, Anda harus memanggil operasi [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html). `Documentation part already exists for the specified location: type 'API'."`
```
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}"
} ]
}
```
Respons yang berhasil mengembalikan kode `200 OK` status dengan payload yang berisi `DocumentationPart` instance yang diperbarui dalam payload.
## Dokumentasikan `RESOURCE` entitas
Untuk menambahkan dokumentasi sumber daya root API, tambahkan sumber [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)daya yang ditargetkan untuk sumber [daya Sumber Daya](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) terkait:
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
Ketika jalur sumber daya tidak ditentukan, sumber daya diasumsikan sebagai sumber daya root. Anda dapat menambahkan `"path": "/"` `properties` untuk membuat spesifikasi eksplisit.
Untuk membuat dokumentasi sumber daya turunan API, tambahkan sumber [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)daya yang ditargetkan untuk sumber [daya Sumber Daya](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) terkait:
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
Untuk menambahkan dokumentasi sumber daya turunan yang ditentukan oleh parameter jalur, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya yang ditargetkan untuk [sumber daya Sumber](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) Daya:
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
**catatan**
[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instance suatu `RESOURCE` entitas tidak dapat diwarisi oleh sumber daya anak mana pun.
## Dokumentasikan `METHOD` entitas
Untuk menambahkan dokumentasi untuk metode API, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya yang ditargetkan untuk sumber daya [Metode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) yang sesuai:
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
Jika `location.method` bidang tidak ditentukan dalam permintaan sebelumnya, diasumsikan sebagai `ANY` metode yang diwakili oleh karakter kartu `*` liar.
Untuk memperbarui konten dokumentasi `METHOD` entitas, panggil operasi [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html), menyediakan peta baru: `properties`
```
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}"
} ]
}
```
Respons yang berhasil mengembalikan kode `200 OK` status dengan payload yang berisi `DocumentationPart` instance yang diperbarui dalam payload. Contoh:
```
{
"_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}"
}
```
## Dokumentasikan `QUERY_PARAMETER` entitas
Untuk menambahkan dokumentasi untuk parameter kueri permintaan, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya yang ditargetkan untuk `QUERY_PARAMETER` jenis, dengan bidang yang valid dari `path` dan`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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
`properties`Peta bagian dokumentasi `QUERY_PARAMETER` entitas dapat diwarisi oleh salah satu `QUERY_PARAMETER` entitas turunannya. Misalnya, jika Anda menambahkan `treats` sumber daya setelahnya`/pets/{petId}`, mengaktifkan `GET` metode`/pets/{petId}/treats`, dan mengekspos parameter `page` kueri, parameter kueri anak ini mewarisi `properties` peta dari parameter kueri yang diberi nama sama dari `GET /pets` metode tersebut, kecuali jika Anda secara eksplisit menambahkan `DocumentationPart` sumber daya ke parameter kueri metode tersebut`page`. `DocumentationPart` `GET /pets/{petId}/treats`
## Dokumentasikan `PATH_PARAMETER` entitas
Untuk menambahkan dokumentasi untuk parameter jalur, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya untuk `PATH_PARAMETER` entitas.
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
## Dokumentasikan `REQUEST_BODY` entitas
Untuk menambahkan dokumentasi untuk badan permintaan, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya untuk badan permintaan.
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
## Dokumentasikan `REQUEST_HEADER` entitas
Untuk menambahkan dokumentasi untuk header permintaan, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya untuk header permintaan.
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
## Dokumentasikan `RESPONSE` entitas
Untuk menambahkan dokumentasi untuk respons kode status, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya yang ditargetkan untuk sumber [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)daya yang sesuai.
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
## Dokumentasikan `RESPONSE_HEADER` entitas
Untuk menambahkan dokumentasi untuk header respons, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya untuk header respons.
```
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}"
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
Dokumentasi header `Content-Type` respons ini adalah dokumentasi default untuk `Content-Type` header dari setiap respons API.
## Dokumentasikan `AUTHORIZER` entitas
Untuk menambahkan dokumentasi bagi otorisasi API, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya yang ditargetkan untuk otorisasi yang ditentukan.
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
**catatan**
[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instance suatu `AUTHORIZER` entitas tidak dapat diwarisi oleh sumber daya anak mana pun.
## Dokumentasikan `MODEL` entitas
Mendokumentasikan `MODEL` entitas melibatkan pembuatan dan pengelolaan `DocumentPart` instance untuk model dan masing-masing model '. `properties` Misalnya, untuk `Error` model yang disertakan dengan setiap API secara default memiliki definisi skema berikut,
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "Error Schema",
"type" : "object",
"properties" : {
"message" : { "type" : "string" }
}
}
```
dan membutuhkan dua `DocumentationPart` contoh, satu untuk `Model` dan yang lainnya untuk `message` propertinya:
```
{
"location": {
"type": "MODEL",
"name": "Error"
},
"properties": {
"title": "Error Schema",
"description": "A description of the Error model"
}
}
```
and
```
{
"location": {
"type": "MODEL",
"name": "Error.message"
},
"properties": {
"description": "An error message."
}
}
```
Saat API diekspor, properti akan mengganti nilai dalam skema asli. `DocumentationPart`
Untuk menambahkan dokumentasi untuk model API, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya yang ditargetkan untuk model yang ditentukan.
```
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}"
}
```
Jika berhasil, operasi mengembalikan `201 Created` respons yang berisi `DocumentationPart` instance yang baru dibuat di payload. Contoh:
```
{
"_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}"
}
```
Ulangi langkah yang sama untuk membuat DocumentationPart instance untuk salah satu properti model.
**catatan**
[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Instance suatu `MODEL` entitas tidak dapat diwarisi oleh sumber daya anak mana pun.
## Perbarui bagian dokumentasi
Untuk memperbarui bagian dokumentasi dari semua jenis entitas API, kirimkan permintaan PATCH pada [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)instance pengidentifikasi bagian tertentu untuk mengganti `properties` peta yang ada dengan yang baru.
```
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"
} ]
}
```
Respons yang berhasil mengembalikan kode `200 OK` status dengan payload yang berisi `DocumentationPart` instance yang diperbarui dalam payload.
Anda dapat memperbarui beberapa bagian dokumentasi dalam satu `PATCH` permintaan.
## Daftar bagian dokumentasi
Untuk mencantumkan bagian dokumentasi dari semua jenis entitas API, kirimkan permintaan GET pada [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)koleksi.
```
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
```
Respons yang berhasil mengembalikan kode `200 OK` status dengan payload yang berisi `DocumentationPart` instance yang tersedia di payload.