Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Representasi dokumentasi API di API Gateway
<a name="api-gateway-documenting-api-content-representation"></a>

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
<a name="api-gateway-documenting-api-content-representation-documentation-parts"></a>

[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
<a name="api-gateway-documenting-api-content-representation-documentation-parts-target"></a>

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
<a name="api-gateway-documenting-api-content-representation-documentation-parts-content"></a>

`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
<a name="api-gateway-documenting-api-content-inheritance"></a>

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`
<a name="api-gateway-documenting-api-content-representation-target-specification"></a>

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) |  <pre>{<br />    "location": {<br />        "type": "API" <br />    }, <br />    ... <br />}</pre>  | type | N/A | Tidak | 
| [Sumber Daya](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) |  <pre>{ <br />    "location": { <br />        "type": "RESOURCE", <br />        "path": "resource_path" <br />    }, <br />    ... <br />}</pre>  | type | Nilai default path adalah /.  | Tidak | 
| [Metode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) |  <pre>{ <br />    "location": { <br />        "type": "METHOD", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | Nilai default path dan method adalah / dan\$1, masing-masing.  | Ya, cocok path dengan awalan dan pencocokan method nilai apa pun.  | 
| Parameter kueri |  <pre>{ <br />    "location": { <br />        "type": "QUERY_PARAMETER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "query_parameter_name" <br />    }, <br />    ... <br />}</pre>  | 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 |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | 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 |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_HEADER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | 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 |  <pre>{ <br />    "location": { <br />        "type": "PATH_PARAMETER", <br />        "path": "resource/{path_parameter_name}", <br />        "method": "HTTP_verb",<br />        "name": "path_parameter_name" <br />    }, <br />    ... <br />}</pre>  | 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 |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | 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 |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_HEADER", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code", <br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | 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 |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | 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) |  <pre>{ <br />    "location": { <br />        "type": "AUTHORIZER", <br />        "name": "authorizer_name" <br />    }, <br />    ... <br />}</pre>  | type | N/A | Tidak | 
| [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) |  <pre>{ <br />    "location": { <br />        "type": "MODEL", <br />        "name": "model_name" <br />    }, <br />    ... <br />}</pre>  | type | N/A | Tidak | 

## Versi dokumentasi
<a name="api-gateway-documenting-api-content-representation-documentation-versions"></a>

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.