Representasi API dokumentasi di API Gateway

APIAPIDokumentasi gateway terdiri dari bagian-bagian dokumentasi individual yang terkait dengan API entitas tertentu yang mencakupAPI, sumber daya, metode, permintaan, respons, parameter pesan (yaitu, jalur, kueri, header), serta otorisasi dan model.

Di API Gateway, bagian dokumentasi diwakili oleh DocumentationPartsumber daya. APIDokumentasi secara keseluruhan diwakili oleh DocumentationPartskoleksi.

Mendokumentasikan sebuah API melibatkan pembuatan DocumentationPart instance, menambahkannya ke DocumentationParts koleksi, dan memelihara versi bagian dokumentasi saat Anda API berkembang.

Bagian dokumentasi

DocumentationPartSumber daya adalah JSON objek yang menyimpan konten dokumentasi yang berlaku untuk API entitas individu. propertiesBidangnya berisi konten dokumentasi sebagai peta pasangan kunci-nilai. locationProperti mengidentifikasi API entitas terkait.

Bentuk peta konten ditentukan oleh Anda, API pengembang. Nilai pasangan kunci-nilai dapat berupa string, angka, boolean, objek, atau array. Bentuk location objek tergantung pada jenis entitas yang ditargetkan.

DocumentationPartSumber daya mendukung pewarisan konten: konten dokumentasi suatu API entitas berlaku untuk anak-anak dari API entitas tersebut. Untuk informasi selengkapnya tentang definisi entitas anak dan pewarisan konten, lihat Mewarisi Konten dari API Entitas Spesifikasi Lebih Umum.

Lokasi bagian dokumentasi

Properti lokasi dari sebuah DocumentationPartinstans mengidentifikasi API entitas yang menerapkan konten terkait. APIEntitas dapat berupa REST API sumber daya API Gateway, seperti, Resource RestApi, Method, MethodResponse, Authorizer, atau Model. Entitas juga dapat berupa parameter pesan, seperti parameter URL jalur, parameter string kueri, parameter header permintaan atau respons, badan permintaan atau respons, atau kode status respons.

Untuk menentukan API entitas, atur atribut tipe location objek menjadi salah satu dariAPI,,,AUTHORIZER,MODEL,RESOURCE,METHOD,PATH_PARAMETER,QUERY_PARAMETER, REQUEST_HEADERREQUEST_BODY,RESPONSE,RESPONSE_HEADER, atauRESPONSE_BODY.

Bergantung pada type API entitas, Anda dapat menentukan location atribut lain, termasuk metode, nama, jalur, dan statusCode. Tidak semua atribut ini valid untuk API entitas tertentu. Misalnya,,type, pathname, dan statusCode merupakan atribut valid dari RESPONSE entitas; hanya type dan path merupakan atribut lokasi yang valid dari RESOURCE entitas. Merupakan kesalahan untuk memasukkan bidang yang tidak valid di location a DocumentationPart untuk entitas tertentuAPI.

Tidak semua location bidang yang valid diperlukan. Misalnya, type adalah location bidang yang valid dan wajib dari semua API entitas. 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. pathNilai defaultnya adalah/, yaitu, sumber daya root dari fileAPI. Nilai defaultmethod, atau statusCode is*, yang berarti metode apa pun, atau nilai kode status, masing-masing.

Isi bagian dokumentasi

propertiesNilai dikodekan sebagai string. JSON propertiesNilai 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 JSON string yang valid sebagai peta konten, atribut konten diperlakukan sebagai dua kategori: yang dapat dikenali oleh Open API dan yang tidak bisa. Dalam contoh sebelumnya,, infodescription, dan x-custom-info diakui oleh Open API sebagai API objek terbuka standar, properti, atau ekstensi. Sebaliknya, my-info tidak sesuai dengan API spesifikasi Terbuka. APIGateway menyebarkan atribut konten API yang sesuai dengan Terbuka ke dalam definisi API entitas dari instance terkait. DocumentationPart APIGateway 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 API entitas dengan spesifikasi yang lebih umum

Nilai default dari 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. APIGateway mengekstrak atribut API dokumentasi Terbuka yang DocumentationPart berlaku dari API entitas generik dan menyuntikkannya ke API entitas tertentu dengan location bidang yang cocok dengan location pola umum, atau mencocokkan nilai yang tepat, kecuali entitas tertentu sudah memiliki DocumentationPart instance yang terkait dengannya. Perilaku ini juga dikenal sebagai pewarisan konten dari API entitas dengan spesifikasi yang lebih umum.

Warisan konten tidak berlaku untuk jenis API entitas tertentu. Lihat tabel di bawah ini untuk detailnya.

Ketika API entitas 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.

Berikut adalah contoh lain untuk membandingkan DocumentationPart contoh yang lebih umum dengan yang lebih spesifik. Pesan kesalahan umum berikut "Invalid request error" disuntikkan ke dalam API definisi Terbuka 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 DocumentationPartsumber daya yang dikaitkan dengan jenis API entitas tertentu.

{
    "location": {
        "type": "API" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}

Versi dokumentasi

Versi dokumentasi adalah snapshot dari DocumentationPartskoleksi API dan ditandai dengan pengenal versi. Menerbitkan dokumentasi API melibatkan pembuatan versi dokumentasi, mengaitkannya dengan API panggung, dan mengekspor versi spesifik tahap API dokumentasi ke file Open eksternal. API Di API Gateway, snapshot dokumentasi direpresentasikan sebagai DocumentationVersionsumber daya.

Saat Anda memperbaruiAPI, Anda membuat versi baru dari fileAPI. Di API Gateway, Anda memelihara semua versi dokumentasi menggunakan DocumentationVersionskoleksi.