Dokumentasikan API menggunakan konsol API Gateway - APIGerbang Amazon
Dokumentasikan API entitasDokumentasikan RESOURCE entitasDokumentasikan METHOD entitasDokumentasikan QUERY_PARAMETER entitasDokumentasikan PATH_PARAMETER entitas Dokumentasikan REQUEST_HEADER entitas Dokumentasikan REQUEST_BODY entitasDokumentasikan RESPONSE entitasDokumentasikan RESPONSE_HEADER entitasDokumentasikan RESPONSE_BODY entitasDokumentasikan MODEL entitasDokumentasikan AUTHORIZER entitas

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

Dokumentasikan API menggunakan konsol API Gateway

Di bagian ini, kami menjelaskan cara membuat dan memelihara bagian dokumentasi dari API sebuah konsol API Gateway.

Prasyarat untuk membuat dan mengedit dokumentasi API adalah bahwa Anda harus sudah membuat. API Di bagian ini, kami menggunakan PetStoreAPIsebagai contoh. Untuk membuat API menggunakan konsol API Gateway, ikuti petunjuk diTutorial: Buat REST API dengan mengimpor contoh.

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.

  2. Untuk jenis Dokumentasi, pilih API.

    Jika bagian dokumentasi tidak dibuat untukAPI, 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 JSON string. Konsol API Gateway membuat string JSON objek untuk Anda.

  3. 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.

  2. Pilih menu APItindakan, lalu pilih Perbarui API dokumentasi.

    Mengedit dokumentasi untuk API entitas di konsol API Gateway

Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:

  1. Di panel Dokumentasi, pilih tab Sumber dan metode.

  2. Pilih nama AndaAPI, dan kemudian pada API kartu, 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.

  2. Untuk jenis Dokumentasi, pilih Sumber Daya.

  3. Untuk Path, masukkan jalan.

  4. Masukkan deskripsi di editor teks, misalnya:

    {
    "description": "The PetStore's root resource."
}

  5. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk sumber daya yang tidak terdaftar.

  6. 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.

  2. Pilih sumber daya, lalu pilih Perbarui dokumentasi.

    Mengedit dokumentasi untuk entitas sumber daya di konsol API Gateway

Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:

  1. Di panel Dokumentasi, pilih tab Sumber dan metode.

  2. 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.

  2. Untuk jenis Dokumentasi, pilih Metode.

  3. Untuk Path, masukkan jalan.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Masukkan deskripsi di editor teks, misalnya:

    {
  "tags" : [ "pets" ],
  "summary" : "List all pets"
}

  6. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk metode yang tidak terdaftar.

  7. 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.

  2. Pilih metode, lalu pilih Perbarui dokumentasi.

    Edit dokumentasi untuk entitas metode di konsol API Gateway

Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:

  1. Di panel Dokumentasi, pilih tab Sumber dan metode.

  2. Anda dapat memilih metode atau memilih sumber daya yang berisi metode, dan kemudian menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.

  3. 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.

  2. Untuk jenis Dokumentasi, pilih Parameter kueri.

  3. Untuk Path, masukkan jalan.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Untuk Nama, masukkan nama.

  6. Masukkan deskripsi di editor teks.

  7. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk parameter kueri yang tidak terdaftar.

  8. 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.

  2. 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.

  3. 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.

  2. Untuk jenis Dokumentasi, pilih parameter Path.

  3. Untuk Path, masukkan jalan.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Untuk Nama, masukkan nama.

  6. Masukkan deskripsi di editor teks.

  7. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk parameter jalur yang tidak terdaftar.

  8. 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.

  2. Anda dapat memilih parameter jalur atau memilih sumber daya yang berisi parameter jalur, lalu menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.

  3. 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.

  2. Untuk jenis Dokumentasi, pilih Request header.

  3. Untuk Path, masukkan jalur untuk header permintaan.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Untuk Nama, masukkan nama.

  6. Masukkan deskripsi di editor teks.

  7. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk header permintaan yang tidak terdaftar.

  8. 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.

  2. 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.

  3. 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.

  2. Untuk jenis Dokumentasi, pilih Request body.

  3. Untuk Path, masukkan jalur untuk badan permintaan.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Masukkan deskripsi di editor teks.

  6. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk badan permintaan yang tidak terdaftar.

  7. 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.

  2. Anda dapat memilih badan permintaan atau memilih sumber daya yang berisi badan permintaan, lalu menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.

  3. 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.

  2. Untuk jenis Dokumentasi, pilih Respons (kode status).

  3. Untuk Path, masukkan jalur untuk respons.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Untuk kode Status, masukkan kode HTTP status.

  6. Masukkan deskripsi di editor teks.

  7. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk kode status respons yang tidak terdaftar.

  8. 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.

  2. 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.

  3. 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.

  2. Untuk jenis Dokumentasi, pilih header Response.

  3. Untuk Path, masukkan jalur untuk header respons.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Untuk kode Status, masukkan kode HTTP status.

  6. Masukkan deskripsi di editor teks.

  7. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk header respons yang tidak terdaftar.

  8. 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.

  2. Anda dapat memilih header respons atau memilih sumber daya yang berisi header respons, lalu gunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.

  3. 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.

  2. Untuk jenis Dokumentasi, pilih Badan respons.

  3. Untuk Path, masukkan jalur untuk badan respons.

  4. Untuk Metode, pilih kata HTTP kerja.

  5. Untuk kode Status, masukkan kode HTTP status.

  6. Masukkan deskripsi di editor teks.

  7. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk badan respons yang tidak terdaftar.

  8. 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.

  2. Anda dapat memilih badan respons atau memilih sumber daya yang berisi badan respons, lalu menggunakan bilah pencarian untuk menemukan dan memilih bagian dokumentasi Anda.

  3. 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 secara API default memiliki definisi skema berikut,

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "Error Schema",
  "type" : "object",
  "properties" : {
    "message" : { "type" : "string" }
  }
}

dan membutuhkan dua DocumentationPart contoh, satu untuk Model dan yang lainnya untuk message propertinya:

{
  "location": {
    "type": "MODEL",
    "name": "Error"
  },
  "properties": {
    "title": "Error Schema",
    "description": "A description of the Error model"
  }
}

and

{
  "location": {
    "type": "MODEL",
    "name": "Error.message"
  },
  "properties": {
    "description": "An error message."
  }
}

Saat API diekspor, properti akan mengganti nilai dalam skema asli. DocumentationPart

Untuk menambahkan bagian dokumentasi baru untuk MODEL entitas, lakukan hal berikut:

  1. Di panel navigasi utama, pilih Dokumentasi, lalu pilih Buat bagian dokumentasi.

  2. Untuk jenis Dokumentasi, pilih Model.

  3. Untuk Nama, masukkan nama untuk model.

  4. Masukkan deskripsi di editor teks.

  5. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk model yang tidak terdaftar.

  6. 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.

  2. Pilih model, lalu pilih Perbarui dokumentasi.

    Edit dokumentasi untuk entitas model di konsol API Gateway

Untuk mengedit bagian dokumentasi yang ada, lakukan hal berikut:

  1. Di panel Dokumentasi, pilih tab Model.

  2. 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.

  2. Untuk jenis Dokumentasi, pilih Authorizer.

  3. Untuk Nama, masukkan nama otorisasi Anda.

  4. Masukkan deskripsi di editor teks. Tentukan nilai untuk location bidang yang valid untuk otorisasi.

  5. Pilih Buat bagian dokumentasi. Anda dapat membuat dokumentasi untuk otorisasi yang tidak terdaftar.

  6. 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.

  2. Gunakan bilah pencarian atau pilih otorisasi, lalu pilih Edit.