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 dari sebuah API menggunakan API Gateway RESTAPI.
Sebelum membuat dan mengedit dokumentasiAPI, pertama buatAPI. Di bagian ini, kami menggunakan PetStore
Topik
- Dokumentasikan API entitas
- Dokumentasikan RESOURCE entitas
- Dokumentasikan METHOD entitas
- Dokumentasikan QUERY_PARAMETER entitas
- Dokumentasikan PATH_PARAMETER entitas
- Dokumentasikan REQUEST_BODY entitas
- Dokumentasikan REQUEST_HEADER entitas
- Dokumentasikan RESPONSE entitas
- Dokumentasikan RESPONSE_HEADER entitas
- Dokumentasikan AUTHORIZER entitas
- Dokumentasikan MODEL entitas
- Perbarui bagian dokumentasi
- Daftar bagian dokumentasi
Dokumentasikan API
entitas
Untuk menambahkan dokumentasi untuk sebuah API, tambahkan DocumentationPartsumber daya untuk API 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" : "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. Sebagai 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. 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 rootAPI, tambahkan sumber daya yang ditargetkan untuk DocumentationPartsumber daya Sumber 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" : { "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. Sebagai 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 untuk sumber daya turunanAPI, tambahkan sumber daya yang ditargetkan untuk DocumentationPartsumber daya Sumber Daya 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. Sebagai 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 DocumentationPartsumber daya yang ditargetkan untuk sumber daya Sumber 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. Sebagai 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
DocumentationPartInstance suatu RESOURCE
entitas tidak dapat diwarisi oleh sumber daya anak mana pun.
Dokumentasikan METHOD
entitas
Untuk menambahkan dokumentasi untuk metodeAPI, tambahkan sumber daya yang ditargetkan untuk DocumentationPartsumber daya Metode 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. Sebagai 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. Sebagai 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, yang 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. Sebagai 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 DocumentationPartsumber daya yang ditargetkan untuk QUERY_PARAMETER
jenis, dengan bidang yang valid dari path
danname
.
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. Sebagai 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 tersebutpage
. DocumentationPart
GET /pets/{petId}/treats
Dokumentasikan PATH_PARAMETER
entitas
Untuk menambahkan dokumentasi untuk parameter jalur, tambahkan DocumentationPartsumber 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. Sebagai 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 DocumentationPartsumber 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. Sebagai 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 DocumentationPartsumber 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. Sebagai 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 DocumentationPartsumber daya yang ditargetkan untuk sumber MethodResponsedaya 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. Sebagai 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 DocumentationPartsumber 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. Sebagai 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 tanggapan dariAPI.
Dokumentasikan AUTHORIZER
entitas
Untuk menambahkan dokumentasi untuk API otorisasi, tambahkan DocumentationPartsumber 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. Sebagai 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
DocumentationPartInstance 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 secara API 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 API model, tambahkan DocumentationPartsumber 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. Sebagai 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
DocumentationPartInstance suatu MODEL
entitas tidak dapat diwarisi oleh sumber daya anak mana pun.
Perbarui bagian dokumentasi
Untuk memperbarui bagian dokumentasi dari semua jenis API entitas, kirimkan PATCH permintaan pada DocumentationPartinstance 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 membuat daftar bagian dokumentasi dari semua jenis API entitas, kirimkan GET permintaan pada DocumentationPartskoleksi.
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.