Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Dokumentasi untuk REST APIs di API Gateway
Untuk membantu pelanggan memahami dan menggunakan API Anda, Anda harus mendokumentasikan API. Untuk membantu Anda mendokumentasikan API, API Gateway memungkinkan Anda menambahkan dan memperbarui konten bantuan untuk entitas API individual sebagai bagian integral dari proses pengembangan API Anda. API Gateway menyimpan konten sumber dan memungkinkan Anda mengarsipkan berbagai versi dokumentasi. Anda dapat mengaitkan versi dokumentasi dengan tahap API, mengekspor snapshot dokumentasi khusus tahap ke file OpenAPI eksternal, dan mendistribusikan file sebagai publikasi dokumentasi.
Untuk mendokumentasikan API Anda, Anda dapat memanggil [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/), menggunakan salah satunya [AWS SDKs](https://aws.amazon.com/developer/tools/), menggunakan [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/)for API Gateway, atau menggunakan konsol API Gateway. Selain itu, Anda dapat mengimpor atau mengekspor bagian dokumentasi yang didefinisikan dalam file OpenAPI eksternal.
Untuk berbagi dokumentasi API dengan pengembang, Anda dapat menggunakan portal pengembang. Sebagai contoh, lihat [Mengintegrasikan ReadMe dengan API Gateway untuk Menjaga Hub Pengembang Anda Tetap Terbaru atau](https://aws.amazon.com/blogs/apn/integrating-readme-with-amazon-api-gateway-to-keep-your-developer-hub-up-to-date/) [Cara Merampingkan Pengembangan API di Amazon API Gateway Menggunakan blog SmartBear](https://aws.amazon.com/blogs/apn/how-to-streamline-api-development-on-amazon-api-gateway-using-smartbear-swaggerhub/) Jaringan AWS Partner (APN). SwaggerHub
**Topics**
+ [Representasi dokumentasi API di API Gateway](api-gateway-documenting-api-content-representation.md)
+ [Dokumentasikan API menggunakan konsol API Gateway](api-gateway-documenting-api-quick-start-with-console.md)
+ [Publikasikan dokumentasi API menggunakan konsol API Gateway](apigateway-documenting-api-with-console.md)
+ [Dokumentasikan API menggunakan API Gateway REST API](api-gateway-documenting-api-quick-start-with-restapi.md)
+ [Publikasikan dokumentasi API menggunakan API Gateway REST API](api-gateway-documenting-api-quick-start-publishing.md)
+ [Impor dokumentasi API](api-gateway-documenting-api-quick-start-import-export.md)
+ [Kontrol akses ke dokumentasi API di API Gateway](api-gateway-documenting-api-content-provision-and-consumption.md)
# Representasi dokumentasi API di API Gateway
Dokumentasi API Gateway API terdiri dari bagian-bagian dokumentasi individual yang terkait dengan entitas API tertentu yang mencakup API, sumber daya, metode, permintaan, respons, parameter pesan (yaitu, jalur, kueri, header), serta otorisasi dan model.
Di API Gateway, bagian dokumentasi diwakili oleh [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya. Dokumentasi API secara keseluruhan diwakili oleh [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html)koleksi.
Mendokumentasikan API melibatkan pembuatan `DocumentationPart` instance, menambahkannya ke `DocumentationParts` koleksi, dan memelihara versi bagian dokumentasi saat API Anda berkembang.
**Topics**
+ [Bagian dokumentasi](#api-gateway-documenting-api-content-representation-documentation-parts)
+ [Versi dokumentasi](#api-gateway-documenting-api-content-representation-documentation-versions)
## Bagian dokumentasi
[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)Sumber daya adalah objek JSON yang menyimpan konten dokumentasi yang berlaku untuk entitas API individual. Ini termasuk konten UTF-8 dan semua bahasa pelokalan utama untuk dokumentasi Anda. `properties`Bidangnya berisi konten dokumentasi sebagai peta pasangan kunci-nilai. `location`Properti mengidentifikasi entitas API terkait.
Bentuk peta konten ditentukan oleh Anda, pengembang API. Nilai pasangan kunci-nilai dapat berupa string, angka, boolean, objek, atau array. Bentuk `location` objek tergantung pada jenis entitas yang ditargetkan.
`DocumentationPart`Sumber daya mendukung pewarisan konten: konten dokumentasi entitas API berlaku untuk turunan dari entitas API tersebut. Untuk informasi selengkapnya tentang definisi entitas turunan dan pewarisan konten, lihat [Mewarisi Konten dari Entitas API dengan Spesifikasi Lebih Umum](#api-gateway-documenting-api-content-inheritance).
### Lokasi bagian dokumentasi
Properti [lokasi [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location)instance mengidentifikasi entitas API yang menerapkan konten terkait. Entitas API dapat berupa sumber API API Gateway REST API, seperti, [Resource [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html), atau [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). Entitas juga dapat berupa parameter pesan, seperti parameter jalur URL, parameter string kueri, parameter header permintaan atau respons, badan permintaan atau respons, atau kode status respons.
Untuk menentukan entitas API, tetapkan atribut [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) `location` objek menjadi salah satu dari`API`,,,`AUTHORIZER`,`MODEL`,`RESOURCE`, `METHOD``PATH_PARAMETER`,`QUERY_PARAMETER`,`REQUEST_HEADER`,`REQUEST_BODY`,`RESPONSE`,`RESPONSE_HEADER`, atau`RESPONSE_BODY`.
Bergantung pada `type` entitas API, Anda dapat menentukan `location` atribut lain, termasuk [metode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [nama](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [jalur](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path), dan [StatusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode). Tidak semua atribut ini valid untuk entitas API tertentu. Misalnya,,`type`, `path``name`, dan `statusCode` merupakan atribut valid dari `RESPONSE` entitas; hanya `type` dan `path` merupakan atribut lokasi yang valid dari `RESOURCE` entitas. Merupakan kesalahan untuk menyertakan bidang yang tidak valid di `location` a `DocumentationPart` untuk entitas API tertentu.
Tidak semua `location` bidang yang valid diperlukan. Misalnya, `type` adalah `location` bidang yang valid dan wajib dari semua entitas API. Namun,`method`,`path`, dan `statusCode` merupakan atribut yang valid tetapi tidak diperlukan untuk `RESPONSE` entitas. Ketika tidak ditentukan secara eksplisit, `location` bidang yang valid mengasumsikan nilai defaultnya. `path`Nilai defaultnya adalah`/`, yaitu sumber daya root dari API. Nilai default`method`, atau `statusCode` is`*`, yang berarti metode apa pun, atau nilai kode status, masing-masing.
### Isi bagian dokumentasi
`properties`Nilai dikodekan sebagai string JSON. `properties`Nilai berisi informasi apa pun yang Anda pilih untuk memenuhi persyaratan dokumentasi Anda. Misalnya, berikut ini adalah peta konten yang valid:
```
{
"info": {
"description": "My first API with Amazon API Gateway."
},
"x-custom-info" : "My custom info, recognized by OpenAPI.",
"my-info" : "My custom info not recognized by OpenAPI."
}
```
Meskipun API Gateway menerima string JSON yang valid sebagai peta konten, atribut konten diperlakukan sebagai dua kategori: atribut yang dapat dikenali oleh OpenAPI dan yang tidak bisa. Dalam contoh sebelumnya,, `info``description`, dan `x-custom-info` diakui oleh OpenAPI sebagai objek OpenAPI standar, properti, atau ekstensi. Sebaliknya, tidak `my-info` sesuai dengan spesifikasi OpenAPI. API Gateway menyebarkan atribut konten yang sesuai dengan OpenAPI ke dalam definisi entitas API dari instance terkait. `DocumentationPart` API Gateway tidak menyebarkan atribut konten yang tidak sesuai ke dalam definisi entitas API.
Sebagai contoh lain, di sini `DocumentationPart` ditargetkan untuk `Resource` entitas:
```
{
"location" : {
"type" : "RESOURCE",
"path": "/pets"
},
"properties" : {
"summary" : "The /pets resource represents a collection of pets in PetStore.",
"description": "... a child resource under the root...",
}
}
```
Di sini, `path` keduanya `type` dan merupakan bidang yang valid untuk mengidentifikasi target `RESOURCE` jenis. Untuk sumber daya root (`/`), Anda dapat menghilangkan `path` bidang.
```
{
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "The root resource with the default path specification."
}
}
```
Ini sama dengan `DocumentationPart` contoh berikut:
```
{
"location" : {
"type" : "RESOURCE",
"path": "/"
},
"properties" : {
"description" : "The root resource with an explicit path specification"
}
}
```
### Mewarisi konten dari entitas API dengan spesifikasi yang lebih umum
Nilai default `location` bidang opsional memberikan deskripsi berpola entitas API. Menggunakan nilai default dalam `location` objek, Anda dapat menambahkan deskripsi umum di `properties` peta ke `DocumentationPart` instance dengan jenis `location` pola ini. API Gateway mengekstrak atribut dokumentasi OpenAPI yang berlaku dari entitas API generik dan menyuntikkannya ke entitas API tertentu dengan `location` bidang yang cocok dengan `location` pola umum, atau mencocokkan nilai persisnya, kecuali entitas tertentu sudah memiliki `DocumentationPart` instance yang terkait dengannya. `DocumentationPart` Perilaku ini juga dikenal sebagai pewarisan konten dari entitas API dengan spesifikasi yang lebih umum.
Warisan konten tidak berlaku untuk tipe entitas API tertentu. Lihat tabel di bawah ini untuk detailnya.
Jika entitas API cocok dengan lebih dari pola lokasi `DocumentationPart` seseorang, entitas akan mewarisi bagian dokumentasi dengan bidang lokasi dengan prioritas dan kekhususan tertinggi. Urutan prioritas adalah `path` >. `statusCode` Untuk mencocokkan dengan `path` bidang, API Gateway memilih entitas dengan nilai jalur paling spesifik. Tabel berikut menunjukkan ini dengan beberapa contoh.
| Kasus | `path` | `statusCode` | `name` | Keterangan |
| --- | --- | --- | --- | --- |
| 1 | /pets | \$1 | id | Dokumentasi yang terkait dengan pola lokasi ini akan diwarisi oleh entitas yang cocok dengan pola lokasi. |
| 2 | /pets | 200 | id | Dokumentasi yang terkait dengan pola lokasi ini akan diwarisi oleh entitas yang cocok dengan pola lokasi ketika Kasus 1 dan Kasus 2 dicocokkan, karena Kasus 2 lebih spesifik daripada Kasus 1. |
| 3 | /pets/petId | \$1 | id | Dokumentasi yang terkait dengan pola lokasi ini akan diwarisi oleh entitas yang cocok dengan pola lokasi ketika Kasus 1, 2, dan 3 dicocokkan, karena Kasus 3 memiliki prioritas yang lebih tinggi daripada Kasus 2 dan lebih spesifik daripada Kasus 1. |
Berikut adalah contoh lain untuk membandingkan `DocumentationPart` contoh yang lebih umum dengan yang lebih spesifik. Pesan kesalahan umum berikut `"Invalid request error"` ini disuntikkan ke dalam definisi OpenAPI dari respons `400` kesalahan, kecuali diganti.
```
{
"location" : {
"type" : "RESPONSE",
"statusCode": "400"
},
"properties" : {
"description" : "Invalid request error."
}"
}
```
Dengan penimpaan berikut, `400` tanggapan terhadap metode apa pun pada `/pets` sumber daya memiliki deskripsi sebagai `"Invalid petId specified"` gantinya.
```
{
"location" : {
"type" : "RESPONSE",
"path": "/pets",
"statusCode": "400"
},
"properties" : "{
"description" : "Invalid petId specified."
}"
}
```
### Bidang lokasi yang valid dari `DocumentationPart`
Tabel berikut menunjukkan bidang yang valid dan wajib serta nilai default yang berlaku dari [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya yang dikaitkan dengan jenis entitas API tertentu.
| Entitas API | Bidang lokasi yang valid | Bidang lokasi yang diperlukan | Nilai bidang default | Konten yang dapat diwariskan |
| --- | --- | --- | --- | --- |
| [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | {
"location": {
"type": "API"
},
...
} | type | N/A | Tidak |
| [Sumber Daya](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | {
"location": {
"type": "RESOURCE",
"path": "resource_path"
},
...
} | type | Nilai default path adalah /. | Tidak |
| [Metode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | {
"location": {
"type": "METHOD",
"path": "resource_path",
"method": "http_verb"
},
...
} | type | Nilai default path dan method adalah / dan\$1, masing-masing. | Ya, cocok path dengan awalan dan pencocokan method nilai apa pun. |
| Parameter kueri | {
"location": {
"type": "QUERY_PARAMETER",
"path": "resource_path",
"method": "HTTP_verb",
"name": "query_parameter_name"
},
...
} | type | Nilai default path dan method adalah / dan\$1, masing-masing. | Ya, mencocokkan path dengan awalan dan mencocokkan method dengan nilai yang tepat. |
| Isi permintaan | {
"location": {
"type": "REQUEST_BODY",
"path": "resource_path",
"method": "http_verb"
},
...
} | type | Nilai default daripath, dan method are / dan\$1, masing-masing. | Ya, mencocokkan path dengan awalan, dan mencocokkan method dengan nilai yang tepat. |
| Permintaan parameter header | {
"location": {
"type": "REQUEST_HEADER",
"path": "resource_path",
"method": "HTTP_verb",
"name": "header_name"
},
...
} | type, name | Nilai default path dan method adalah / dan\$1, masing-masing. | Ya, mencocokkan path dengan awalan dan mencocokkan method dengan nilai yang tepat. |
| Parameter jalur permintaan | {
"location": {
"type": "PATH_PARAMETER",
"path": "resource/{path_parameter_name}",
"method": "HTTP_verb",
"name": "path_parameter_name"
},
...
} | type, name | Nilai default path dan method adalah / dan\$1, masing-masing. | Ya, mencocokkan path dengan awalan dan mencocokkan method dengan nilai yang tepat. |
| Respons | {
"location": {
"type": "RESPONSE",
"path": "resource_path",
"method": "http_verb",
"statusCode": "status_code"
},
...
} | type | Nilai default daripath,method, dan statusCode adalah/, \$1 dan\$1, masing-masing. | Ya, cocok path dengan awalan dan pencocokan method dan statusCode dengan nilai yang tepat. |
| Header respons | {
"location": {
"type": "RESPONSE_HEADER",
"path": "resource_path",
"method": "http_verb",
"statusCode": "status_code",
"name": "header_name"
},
...
} | type, name | Nilai default daripath, method dan statusCode are/, \$1 dan\$1, masing-masing. | Ya, cocok path dengan awalan dan pencocokanmethod, dan statusCode dengan nilai yang tepat. |
| Isi respons | {
"location": {
"type": "RESPONSE_BODY",
"path": "resource_path",
"method": "http_verb",
"statusCode": "status_code"
},
...
} | type | Nilai default daripath, method dan statusCode are/, \$1 dan\$1, masing-masing. | Ya, cocok path dengan awalan dan pencocokanmethod, dan statusCode dengan nilai yang tepat. |
| [Pengotorisasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | {
"location": {
"type": "AUTHORIZER",
"name": "authorizer_name"
},
...
} | type | N/A | Tidak |
| [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | {
"location": {
"type": "MODEL",
"name": "model_name"
},
...
} | type | N/A | Tidak |
## Versi dokumentasi
Versi dokumentasi adalah snapshot dari [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)koleksi API dan ditandai dengan pengenal versi. Menerbitkan dokumentasi API melibatkan pembuatan versi dokumentasi, mengaitkannya dengan tahap API, dan mengekspor versi spesifik tahap dokumentasi API ke file OpenAPI eksternal. Di API Gateway, snapshot dokumentasi direpresentasikan sebagai [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)sumber daya.
Saat memperbarui API, Anda membuat versi API yang baru. Di API Gateway, Anda memelihara semua versi dokumentasi menggunakan [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)koleksi.
# Dokumentasikan API menggunakan konsol API Gateway
Di bagian ini, kami menjelaskan cara membuat dan memelihara bagian dokumentasi API menggunakan konsol API Gateway.
Prasyarat untuk membuat dan mengedit dokumentasi API adalah Anda harus sudah membuat 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-document-api-add-document-part-for-api-entity-with-console)
+ [Dokumentasikan `RESOURCE` entitas](#api-gateway-document-api-add-document-part-for-resource-entity-with-console)
+ [Dokumentasikan `METHOD` entitas](#api-gateway-document-api-add-document-part-for-method-entity-with-console)
+ [Dokumentasikan `QUERY_PARAMETER` entitas](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console)
+ [Dokumentasikan `PATH_PARAMETER` entitas](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console)
+ [Dokumentasikan `REQUEST_HEADER` entitas](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console)
+ [Dokumentasikan `REQUEST_BODY` entitas](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console)
+ [Dokumentasikan `RESPONSE` entitas](#api-gateway-document-api-add-document-part-for-response-with-console)
+ [Dokumentasikan `RESPONSE_HEADER` entitas](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console)
+ [Dokumentasikan `RESPONSE_BODY` entitas](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console)
+ [Dokumentasikan `MODEL` entitas](#api-gateway-document-api-add-document-part-for-model-entity-with-console)
+ [Dokumentasikan `AUTHORIZER` entitas](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console)
## Dokumentasikan `API` entitas
Untuk menambahkan bagian dokumentasi baru untuk `API` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **API**.
Jika bagian dokumentasi tidak dibuat untuk`API`, Anda mendapatkan editor `properties` peta bagian dokumentasi. Masukkan `properties` peta berikut di editor teks.
```
{
"info": {
"description": "Your first API Gateway API.",
"contact": {
"name": "John Doe",
"email": "john.doe@api.com"
}
}
}
```
**catatan**
Anda tidak perlu menyandikan `properties` peta menjadi string JSON. Konsol API Gateway membuat stringifikasi objek JSON untuk Anda.
1. Pilih **Buat bagian dokumentasi**.
Untuk menambahkan bagian dokumentasi baru untuk `API` entitas di panel **Resources**, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Resources**.
1. Pilih menu **tindakan API**, lalu pilih **Perbarui dokumentasi API**.
![\[Edit dokumentasi untuk entitas API di konsol API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png)
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Pilih nama API Anda, lalu pada kartu API, pilih **Edit**.
## Dokumentasikan `RESOURCE` entitas
Untuk menambahkan bagian dokumentasi baru untuk `RESOURCE` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Sumber Daya**.
1. Untuk **Path**, masukkan jalan.
1. Masukkan deskripsi di editor teks, misalnya:
```
{
"description": "The PetStore's root resource."
}
```
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk sumber daya yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk menambahkan bagian dokumentasi baru untuk `RESOURCE` entitas di panel **Resources**, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Resources**.
1. Pilih sumber daya, lalu pilih **Perbarui dokumentasi**.
![\[Mengedit dokumentasi untuk entitas sumber daya di konsol API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png)
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Pilih sumber daya yang berisi bagian dokumentasi Anda, lalu pilih **Edit**.
## Dokumentasikan `METHOD` entitas
Untuk menambahkan bagian dokumentasi baru untuk `METHOD` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Metode**.
1. Untuk **Path**, masukkan jalan.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Masukkan deskripsi di editor teks, misalnya:
```
{
"tags" : [ "pets" ],
"summary" : "List all pets"
}
```
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk metode yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk menambahkan bagian dokumentasi baru untuk `METHOD` entitas di panel **Resources**, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Resources**.
1. Pilih metode, lalu pilih **Perbarui dokumentasi**.
![\[Edit dokumentasi untuk entitas metode di konsol API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png)
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih metode atau memilih sumber daya yang berisi metode, dan kemudian menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## Dokumentasikan `QUERY_PARAMETER` entitas
Untuk menambahkan bagian dokumentasi baru untuk `QUERY_PARAMETER` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Parameter kueri**.
1. Untuk **Path**, masukkan jalan.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Untuk **Nama**, masukkan nama.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk parameter kueri yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih parameter kueri atau memilih sumber daya yang berisi parameter kueri, dan kemudian menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## Dokumentasikan `PATH_PARAMETER` entitas
Untuk menambahkan bagian dokumentasi baru untuk `PATH_PARAMETER` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **parameter Path**.
1. Untuk **Path**, masukkan jalan.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Untuk **Nama**, masukkan nama.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk parameter jalur yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih parameter jalur atau memilih sumber daya yang berisi parameter jalur, lalu menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## Dokumentasikan `REQUEST_HEADER` entitas
Untuk menambahkan bagian dokumentasi baru untuk `REQUEST_HEADER` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Request header**.
1. Untuk **Path**, masukkan jalur untuk header permintaan.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Untuk **Nama**, masukkan nama.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk header permintaan yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih header permintaan atau memilih sumber daya yang berisi header permintaan, dan kemudian menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## Dokumentasikan `REQUEST_BODY` entitas
Untuk menambahkan bagian dokumentasi baru untuk `REQUEST_BODY` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Request body**.
1. Untuk **Path**, masukkan jalur untuk badan permintaan.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk badan permintaan yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih badan permintaan atau memilih sumber daya yang berisi badan permintaan, lalu menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## Dokumentasikan `RESPONSE` entitas
Untuk menambahkan bagian dokumentasi baru untuk `RESPONSE` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Respons (kode status)**.
1. Untuk **Path**, masukkan jalur untuk respons.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Untuk **kode Status**, masukkan kode status HTTP.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk kode status respons yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih kode status respons atau memilih sumber daya yang berisi kode status respons, lalu gunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## Dokumentasikan `RESPONSE_HEADER` entitas
Untuk menambahkan bagian dokumentasi baru untuk `RESPONSE_HEADER` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **header Response**.
1. Untuk **Path**, masukkan jalur untuk header respons.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Untuk **kode Status**, masukkan kode status HTTP.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk header respons yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih header respons atau memilih sumber daya yang berisi header respons, lalu gunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## Dokumentasikan `RESPONSE_BODY` entitas
Untuk menambahkan bagian dokumentasi baru untuk `RESPONSE_BODY` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Badan respons**.
1. Untuk **Path**, masukkan jalur untuk badan respons.
1. Untuk **Metode**, pilih kata kerja HTTP.
1. Untuk **kode Status**, masukkan kode status HTTP.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk badan respons yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Sumber dan metode**.
1. Anda dapat memilih badan respons atau memilih sumber daya yang berisi badan respons, lalu menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.
1. Pilih **Edit**.
## 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 bagian dokumentasi baru untuk `MODEL` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Model**.
1. Untuk **Nama**, masukkan nama untuk model.
1. Masukkan deskripsi di editor teks.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk model yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi ke model lain.
Untuk menambahkan bagian dokumentasi baru untuk `MODEL` entitas di panel **Model**, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Model**.
1. Pilih model, lalu pilih **Perbarui dokumentasi**.
![\[Edit dokumentasi untuk entitas model di konsol API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png)
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Model**.
1. Gunakan bilah pencarian atau pilih model, lalu pilih **Edit**.
## Dokumentasikan `AUTHORIZER` entitas
Untuk menambahkan bagian dokumentasi baru untuk `AUTHORIZER` entitas, lakukan hal berikut:
1. Di panel navigasi utama, pilih **Dokumentasi**, lalu pilih **Buat bagian dokumentasi**.
1. Untuk **jenis Dokumentasi**, pilih **Authorizer**.
1. Untuk **Nama**, masukkan nama otorisasi Anda.
1. Masukkan deskripsi di editor teks. Tentukan nilai untuk `location` bidang yang valid untuk otorisasi.
1. Pilih **Buat bagian dokumentasi**. Anda dapat membuat dokumentasi untuk otorisasi yang tidak terdaftar.
1. Jika diperlukan, ulangi langkah-langkah ini untuk menambah atau mengedit bagian dokumentasi ke otorisasi lain.
Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:
1. Di panel **Dokumentasi**, pilih tab **Authorizers**.
1. Gunakan bilah pencarian atau pilih otorisasi, lalu pilih **Edit**.
# Publikasikan dokumentasi API menggunakan konsol API Gateway
Prosedur berikut menjelaskan cara mempublikasikan versi dokumentasi.
**Untuk memublikasikan versi dokumentasi menggunakan konsol API Gateway**
1. Di panel navigasi utama, pilih **Dokumentasi**.
1. Pilih **Publikasikan dokumentasi**.
1. Siapkan publikasi:
1. Untuk **Stage**, pilih panggung.
1. Untuk **Versi**, masukkan pengenal versi, misalnya,`1.0.0`.
1. (Opsional) Untuk **Deskripsi**, masukkan deskripsi.
1. Pilih **Terbitkan**.
Anda sekarang dapat melanjutkan untuk mengunduh dokumentasi yang diterbitkan dengan mengekspor dokumentasi ke file OpenAPI eksternal. Untuk mempelajari selengkapnya, lihat [Ekspor REST API dari API Gateway](api-gateway-export-api.md).
# 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.
# Publikasikan dokumentasi API menggunakan API Gateway REST API
Untuk memublikasikan dokumentasi untuk API, buat, perbarui, atau dapatkan snapshot dokumentasi, lalu kaitkan snapshot dokumentasi dengan tahap API. Saat membuat snapshot dokumentasi, Anda juga dapat mengaitkannya dengan tahap API secara bersamaan.
**Topics**
+ [Buat snapshot dokumentasi dan kaitkan dengan tahap API](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [Buat snapshot dokumentasi](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [Perbarui snapshot dokumentasi](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [Dapatkan snapshot dokumentasi](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [Kaitkan snapshot dokumentasi dengan tahap API](#api-gateway-documenting-api-publishing-stage-association)
+ [Unduh snapshot dokumentasi yang terkait dengan panggung](#api-gateway-documenting-api-publishing-export-documentation-version)
## Buat snapshot dokumentasi dan kaitkan dengan tahap API
Untuk membuat snapshot bagian dokumentasi API dan mengaitkannya dengan tahap API secara bersamaan, kirimkan `POST` permintaan berikut:
```
POST /restapis/restapi_id/documentation/versions 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
{
"documentationVersion" : "1.0.0",
"stageName": "prod",
"description" : "My API Documentation v1.0.0"
}
```
Jika berhasil, operasi mengembalikan `200 OK` respons, yang berisi `DocumentationVersion` instance yang baru dibuat sebagai muatan.
Atau, Anda dapat membuat snapshot dokumentasi tanpa mengaitkannya dengan tahap API terlebih dahulu dan kemudian memanggil [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) untuk mengaitkan snapshot dengan tahap API tertentu. Anda juga dapat memperbarui atau menanyakan snapshot dokumentasi yang ada dan kemudian memperbarui asosiasi tahapannya. Kami menunjukkan langkah-langkah di empat bagian berikutnya.
## Buat snapshot dokumentasi
Untuk membuat snapshot bagian dokumentasi API, buat [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)resource baru dan tambahkan ke [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)koleksi API:
```
POST /restapis/restapi_id/documentation/versions 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
{
"documentationVersion" : "1.0.0",
"description" : "My API Documentation v1.0.0"
}
```
Jika berhasil, operasi mengembalikan `200 OK` respons, yang berisi `DocumentationVersion` instance yang baru dibuat sebagai muatan.
## Perbarui snapshot dokumentasi
Anda hanya dapat memperbarui snapshot dokumentasi dengan memodifikasi `description` properti sumber daya yang sesuai [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html). Contoh berikut menunjukkan cara memperbarui deskripsi snapshot dokumentasi seperti yang diidentifikasi oleh pengenal versinya, misalnya`version`,. `1.0.0`
```
PATCH /restapis/restapi_id/documentation/versions/version 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": "/description",
"value": "My API for testing purposes."
}]
}
```
Jika berhasil, operasi mengembalikan `200 OK` respons, yang berisi `DocumentationVersion` instance yang diperbarui sebagai muatan.
## Dapatkan snapshot dokumentasi
Untuk mendapatkan snapshot dokumentasi, kirimkan `GET` permintaan terhadap [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html)sumber daya yang ditentukan. Contoh berikut menunjukkan cara mendapatkan snapshot dokumentasi dari pengenal versi tertentu, 1.0.0.
```
GET /restapis//documentation/versions/1.0.0 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
```
## Kaitkan snapshot dokumentasi dengan tahap API
Untuk mempublikasikan dokumentasi API, kaitkan snapshot dokumentasi dengan tahap API. Anda harus sudah membuat tahap API sebelum mengaitkan versi dokumentasi dengan stage.
Untuk mengaitkan snapshot dokumentasi dengan tahap API menggunakan API [Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/), panggil operasi [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) untuk menyetel versi dokumentasi yang diinginkan di properti: `stage.documentationVersion`
```
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
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": "/documentationVersion",
"value": "VERSION_IDENTIFIER"
}]
}
```
## Unduh snapshot dokumentasi yang terkait dengan panggung
Setelah versi bagian dokumentasi dikaitkan dengan tahapan, Anda dapat mengekspor bagian dokumentasi bersama dengan definisi entitas API, ke file eksternal, menggunakan konsol API Gateway, API Gateway REST API, salah satunya SDKs, atau AWS CLI untuk API Gateway. Prosesnya sama dengan mengekspor API. Format file yang diekspor dapat berupa JSON atau YAMB.
Menggunakan API Gateway REST API, Anda juga dapat secara eksplisit menyetel parameter `extension=documentation,integrations,authorizers` kueri untuk menyertakan bagian dokumentasi API, integrasi API, dan otorisasi dalam ekspor API. Secara default, bagian dokumentasi disertakan, tetapi integrasi dan otorisasi dikecualikan, saat Anda mengekspor API. Output default dari ekspor API cocok untuk distribusi dokumentasi.
Untuk mengekspor dokumentasi API dalam file OpenAPI JSON eksternal menggunakan API Gateway REST API, kirimkan permintaan berikut`GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
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
```
Di sini, `x-amazon-apigateway-documentation` objek berisi bagian dokumentasi dan definisi entitas API berisi properti dokumentasi yang didukung oleh OpenAPI. Output tidak termasuk rincian integrasi atau otorisasi Lambda (sebelumnya dikenal sebagai otorisasi khusus). Untuk memasukkan kedua detail, atur`extensions=integrations,authorizers,documentation`. Untuk menyertakan detail integrasi tetapi bukan otorisasi, atur. `extensions=integrations,documentation`
Anda harus mengatur `Accept:application/json` header dalam permintaan untuk menampilkan hasil dalam file JSON. Untuk menghasilkan output YAMM, ubah header permintaan menjadi`Accept:application/yaml`.
Sebagai contoh, kita akan melihat API yang mengekspos `GET` metode sederhana pada sumber daya root (`/`). API ini memiliki empat entitas API yang didefinisikan dalam file definisi OpenAPI, satu untuk masing-masing`API`,, `MODEL``METHOD`, dan `RESPONSE` tipe. Bagian dokumentasi telah ditambahkan ke masing-masing`API`,`METHOD`, dan `RESPONSE` entitas. Memanggil perintah documentation-exporting sebelumnya, kita mendapatkan output berikut, dengan bagian-bagian dokumentasi yang tercantum dalam `x-amazon-apigateway-documentation` objek sebagai ekstensi ke file OpenAPI standar.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
Untuk atribut yang sesuai dengan OpenAPI yang ditentukan dalam `properties` peta bagian dokumentasi, API Gateway menyisipkan atribut ke dalam definisi entitas API terkait. Atribut `x-something` adalah ekstensi OpenAPI standar. Ekstensi ini disebarkan ke dalam definisi entitas API. Misalnya, lihat `x-example` atribut untuk `GET` metode. Atribut seperti `foo` bukan bagian dari spesifikasi OpenAPI dan tidak disuntikkan ke dalam definisi entitas API terkait.
Jika alat rendering dokumentasi (misalnya, [OpenAPI UI) mem-parsing definisi entitas API](https://swagger.io/tools/swagger-ui/) untuk mengekstrak atribut dokumentasi, atribut 'instance' yang tidak sesuai dengan OpenAPI `properties` tidak tersedia untuk alat tersebut. `DocumentationPart` Namun, jika alat rendering dokumentasi mem-parsing `x-amazon-apigateway-documentation` objek untuk mendapatkan konten, atau jika alat memanggil [restapi:documentation-parts dan documenationpart:by-id untuk mengambil bagian](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) [dokumentasi dari API Gateway, semua atribut dokumentasi tersedia](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) untuk ditampilkan oleh alat tersebut.
Untuk mengekspor dokumentasi dengan definisi entitas API yang berisi detail integrasi ke file OpenAPI JSON, kirimkan permintaan berikut`GET`:
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
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
```
Untuk mengekspor dokumentasi dengan definisi entitas API yang berisi detail integrasi dan otorisasi ke file OpenAPI YAMAL, kirimkan permintaan berikut: `GET`
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
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
```
Untuk menggunakan konsol API Gateway untuk mengekspor dan mengunduh dokumentasi API yang dipublikasikan, ikuti petunjuk di[Ekspor REST API menggunakan konsol API Gateway](api-gateway-export-api.md#api-gateway-export-api-from-console).
# Impor dokumentasi API
Seperti halnya mengimpor definisi entitas API, Anda dapat mengimpor bagian dokumentasi dari file OpenAPI eksternal ke API di API Gateway. Anda menentukan bagian to-be-imported dokumentasi dalam [x-amazon-apigateway-documentation objek](api-gateway-swagger-extensions-documentation.md) ekstensi dalam file definisi OpenAPI yang valid. Mengimpor dokumentasi tidak mengubah definisi entitas API yang ada.
Anda memiliki opsi untuk menggabungkan bagian dokumentasi yang baru ditentukan ke dalam bagian dokumentasi yang ada di API Gateway atau menimpa bagian dokumentasi yang ada. Dalam `MERGE` mode, bagian dokumentasi baru yang ditentukan dalam file OpenAPI ditambahkan ke `DocumentationParts` koleksi API. Jika impor `DocumentationPart` sudah ada, atribut yang diimpor menggantikan yang sudah ada jika keduanya berbeda. Atribut dokumentasi lain yang ada tetap tidak terpengaruh. Dalam `OVERWRITE` mode, seluruh `DocumentationParts` koleksi diganti sesuai dengan file definisi OpenAPI yang diimpor.
## Mengimpor bagian dokumentasi menggunakan API Gateway REST API
Untuk mengimpor dokumentasi API menggunakan API Gateway REST API, panggil operasi [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html). Contoh berikut menunjukkan cara menimpa bagian dokumentasi API yang ada dengan satu `GET / ` metode, mengembalikan `200 OK` respons saat berhasil.
------
#### [ OpenAPI 3.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
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
{
"openapi": "3.0.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
}
}
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
},
"servers": [
{
"url": "/"
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
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
{
"swagger": "2.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"host": "",
"basePath": "/",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"description": "Method description.",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
}
}
```
------
Jika berhasil, permintaan ini mengembalikan respons 200 OK yang berisi impor `DocumentationPartId` dalam muatan.
```
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
```
Selain itu, Anda juga dapat memanggil [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) atau [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html), memasok bagian dokumentasi dalam objek `x-amazon-apigateway-documentation` sebagai bagian dari file OpenAPI input dari definisi API. Untuk mengecualikan bagian dokumentasi dari impor API, atur `ignore=documentation` parameter kueri permintaan.
## Mengimpor bagian dokumentasi menggunakan konsol API Gateway
Petunjuk berikut menjelaskan cara mengimpor bagian dokumentasi.
**Untuk menggunakan konsol untuk mengimpor bagian dokumentasi API dari file eksternal**
1. Di panel navigasi utama, pilih **Dokumentasi**.
1. Pilih **Impor**.
1. Jika Anda memiliki dokumentasi yang sudah ada, pilih untuk **Menimpa atau **Menggabungkan**** dokumentasi baru Anda.
1. Pilih **Pilih file** untuk memuat file dari drive, atau masukkan konten file ke dalam tampilan file. Sebagai contoh, lihat payload permintaan contoh di[Mengimpor bagian dokumentasi menggunakan API Gateway REST API](#api-gateway-importing-api-with-swagger-file-using-rest-api).
1. Pilih cara menangani peringatan saat impor. Pilih salah satu **Gagal pada peringatan** atau **Abaikan peringatan**. Untuk informasi selengkapnya, lihat [Kesalahan dan peringatan dari mengimpor API Anda ke API Gateway](api-gateway-import-api-errors-warnings.md).
1. Pilih **Impor**.
# Kontrol akses ke dokumentasi API di API Gateway
Jika Anda memiliki tim dokumentasi khusus untuk menulis dan mengedit dokumentasi API Anda, Anda dapat mengonfigurasi izin akses terpisah untuk pengembang Anda (untuk pengembangan API) dan untuk penulis atau editor Anda (untuk pengembangan konten). Ini sangat tepat ketika vendor pihak ketiga terlibat dalam membuat dokumentasi untuk Anda.
Untuk memberi tim dokumentasi Anda akses untuk membuat, memperbarui, dan memublikasikan dokumentasi API Anda, Anda dapat menetapkan peran IAM kepada tim dokumentasi dengan kebijakan IAM berikut, di mana *account\$1id* ID AWS akun tim dokumentasi Anda.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "StmtDocPartsAddEditViewDelete",
"Effect": "Allow",
"Action": [
"apigateway:GET",
"apigateway:PUT",
"apigateway:POST",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1:111111111111:/restapis/*/documentation/*"
]
}
]
}
```
------
Untuk informasi tentang menyetel izin untuk mengakses sumber daya API Gateway, lihat[Cara kerja Amazon API Gateway dengan IAM](security_iam_service-with-iam.md).