Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# 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).