Menggunakan SmartDocs untuk mendokumentasikan API

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

SmartDocs memungkinkan Anda mendokumentasikan API di portal developer Drupal 7 dengan cara yang membuat dokumentasi API menjadi sangat interaktif. Dokumentasi interaktif berarti pengguna portal dapat:

  • Baca tentang API Anda
  • Mengirim permintaan langsung ke API
  • Melihat respons langsung yang ditampilkan dari API

Dengan membuat dokumentasi interaktif di API, Anda memudahkan pengguna portal untuk mempelajari, menguji, dan mengevaluasi API Anda.

Edge management API adalah RESTful API yang memungkinkan Anda mengakses Layanan API menggunakan klien HTTP apa pun. Apigee menggunakan SmartDocs untuk membuat dokumentasi interaktif bagi Edge Management API. Lihat dokumentasi API tersebut di sini.

Contoh portal SmartDocs

Untuk menggunakan SmartDocs, Anda harus memiliki portal Layanan Developer Apigee. Untuk informasi selengkapnya, lihat Membuat portal developer.

Dari halaman beranda portal developer Anda, klik API di menu navigasi atas untuk melihat halaman Dokumentasi API.

Ada dua API yang didokumentasikan di portal: Hello World dan Pet Store Example.

Hello World API dibuat dari Spesifikasi OpenAPI target tiruan, mocktarget.yaml. Untuk informasi selengkapnya, lihat https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

Pet Store Example API dibuat dari demo toko hewan peliharaan klasik.

Jelajahi Hello World API:

  1. Klik Hello World API. Halaman ringkasan Hello World API ditampilkan:
  2. Klik Lihat afirmasi API. SmartDocs untuk referensi ini ditampilkan:
  3. Klik Kirim permintaan ini.
  4. Lihat respons yang ditampilkan: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. Klik tab Request untuk melihat permintaan, atau tab cURL untuk melihat panggilan cURL yang sesuai.

Cara mendokumentasikan API menggunakan SmartDocs

SmartDocs mewakili API Anda menggunakan model, dengan model yang berisi semua informasi tentang API Anda. Portal ini mengekstrak informasi tentang API Anda dari model untuk merender halaman dokumentasi di portal sebagai node Drupal, dengan setiap node Drupal sesuai dengan halaman dokumentasi di portal.

Langkah-langkah umum yang Anda ikuti untuk menggunakan SmartDocs adalah:

  1. Konfigurasi modul Drupal SmartDocs di portal.
  2. Buat model SmartDocs.
  3. Menambahkan API ke model dari file WADL, spesifikasi OpenAPI (sebelumnya Swagger), atau secara manual.
  4. Render model sebagai kumpulan node Drupal. Setiap node Drupal berisi informasi tentang satu API. Misalnya, jika resource di API Anda mendukung permintaan POST dan PUT, SmartDocs akan membuat node Drupal terpisah untuk POST dan PUT.
  5. Publikasikan node Drupal. Setelah dipublikasikan, pengguna portal Anda dapat melihat dan berinteraksi dengan API Anda.
  6. Edit node Drupal, sebelum atau setelah memublikasikannya. Anda dapat mengedit node Drupal dengan menggunakan editor Drupal atau dengan mengedit file WADL asli atau Spesifikasi OpenAPI. Setelah selesai mengedit file WADL atau Spesifikasi OpenAPI, impor kembali ke model sebagai revisi baru, lalu render dan publikasikan perubahan Anda.
  7. Aktifkan TLS. Karena SmartDocs dapat mengirim kredensial autentikasi ke backend Anda sebagai bagian dari pembuatan permintaan ke API, Anda harus mengaktifkan TLS di portal untuk memastikan bahwa kredensial tersebut aman. Dalam lingkungan produksi dan pengujian portal, Apigee menyediakan sertifikat TLS yang diperlukan untuk membuat permintaan https://. Namun, sebelum mengakses portal, Anda harus mendapatkan sertifikat TLS sendiri dan mengaktifkan TLS. Untuk informasi selengkapnya, lihat Menggunakan TLS di portal.

Tentang model dan template SmartDoc

Saat Anda membuat model di portal, model tersebut sebenarnya disimpan di organisasi Edge, bukan di Drupal. Model adalah blok besar JSON dengan nama internal (seperti "my-smartdocs-api"), dan menentukan struktur API. Di sisi lain, portal Anda merender model dalam HTML dan menyediakan antarmuka pengeditan untuk model tersebut. Setiap update pada API di portal akan otomatis dikirim kembali ke model sumber.

Disimpan dalam organisasi

Disimpan di Drupal

model

templates

Node drupal dengan fungsi pengeditan

Asumsikan bahwa Anda memiliki beberapa portal di organisasi (misalnya, pengembangan, tahap, dan produksi). Di Pantheon, Anda memindahkan portal dari satu lingkungan ke lingkungan lainnya. Setiap instance portal terlihat berisi modelnya sendiri, tetapi semuanya benar-benar merujuk ke model sumber. Jika Anda mengedit API di Developer, model akan diupdate, dan perubahan akan muncul di produksi. Demikian pula, jika Anda menghapus model di dev, sumbernya akan dihapus, dan tidak lagi tersedia di produksi.

Template mengontrol tampilan dan nuansa SmartDocs, dan template tersebut (diatur oleh Handlebar dan file CSS) disimpan dengan setiap instance portal. Jadi, setiap portal secara teoritis dapat menggunakan template unik untuk setiap model. Namun, salah satu kepraktisan dari framework rendering adalah template default (baik default Apigee maupun template yang Anda berikan) otomatis diterapkan ke setiap model.

Diagram berikut menunjukkan hubungan antara model dan portal. Panah hijau menunjukkan sinkronisasi otomatis.

Perintah cURL berikut mencantumkan semua model di organisasi Anda:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Mengonfigurasi modul SmartDocs

Apigee mengimplementasikan SmartDocs sebagai modul Drupal kustom. Gunakan prosedur berikut untuk mengonfigurasi modul SmartDocs.

Untuk mengonfigurasi modul SmartDocs:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Modules di menu administrasi Drupal. Daftar semua modul Drupal yang terinstal akan muncul.
  3. Aktifkan modul SmartDocs.
  4. Simpan konfigurasi.
  5. Pilih Modules di menu admin Drupal.
  6. Pilih SmartDocs -> Izin dan pastikan "Lakukan tugas administrasi untuk modul SmartDocs" untuk peran "Administrator" diaktifkan.
  7. Pilih Configuration > Dev Portal di menu administrasi Drupal.
  8. Tetapkan Connection Timeout dan Request Timeout ke 16 detik.
  9. Simpan konfigurasi.
  10. Konfigurasikan setelan URL:
    1. Dari menu Drupal, pilih Configuration > Search and metadata > URL alias > Settings.
    2. Tetapkan Maximum alias length dan Maximum component length ke 255.
    3. Luaskan Tanda baca.
    4. Untuk setelan Kurung kurawal buka ({) dan Tanda kurung kurawal kanan (}), pilih No action (do not replace).
    5. Klik Save configuration.
  11. Jika portal developer Anda terekspos ke pengguna di jaringan internal tanpa akses ke internet atau jika sebagian API Anda berada di jaringan pribadi, konfigurasikan URL proxy SmartDocs API, sebagai berikut:
    1. Pilih Configuration > SmartDocs di menu Drupal Administration.
    2. Luaskan Setelan Lanjutan.
    3. Perbarui kolom URL proxy SmartDocs sebagai berikut: <host>/smartdocs/v1/sendrequest.
      Bantuan inline akan memberikan nilai yang diperlukan untuk lingkungan Anda. Misalnya:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      Kolom ini ditetapkan secara default ke https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Klik Save configuration.

Membuat model

Model berisi semua informasi tentang representasi API Anda. Anda dapat menentukan beberapa model di portal untuk mendukung berbagai API, atau mengelompokkan semua API Anda ke dalam satu model.

Setiap model menentukan nama internal unik yang juga menentukan URL dasar dari node Drupal yang dihasilkan. URL setiap node Drupal berbentuk:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

dalam hal ini:

  • drupalBasePath: URL dasar portal Anda.
  • internalName: Nama internal model.
  • httpMethod: Metode HTTP API, seperti: get, put, post, atau delete.
  • resourcePath: Jalur resource.

Misalnya, jika Anda menentukan nama internal sebagai 'mymodel', URL untuk node Drupal yang dihasilkan untuk permintaan GET ke resource bernama '/books' adalah:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

Untuk membuat model

Saat Anda membuat model, model tersebut disimpan di organisasi Edge Anda sebagai sumber struktur API. Untuk informasi selengkapnya, lihat Tentang model dan template SmartDoc.

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Pilih Model baru di bagian atas halaman.
  4. Masukkan kolom berikut:
    • Nama: Nama model yang akan ditampilkan di seluruh situs.
    • Internal name: Saat Anda mengetik Name, nama internal akan ditampilkan. Nama internal untuk model yang harus unik di antara semua model. Nama internal hanya boleh berisi huruf kecil, angka, dan tanda hubung tanpa spasi. Pilih Edit untuk mengedit nama ini.
    • Deskripsi: Deskripsi model.
  5. Pilih Create Model.

Setelah membuat model, Anda akan dialihkan ke halaman model. Dari sana, Anda dapat menggunakan drop-down Operations bx untuk:

  • Impor file WADL yang mendeskripsikan API Anda atau tentukan URL Spesifikasi OpenAPI yang mendeskripsikan API Anda.
  • Menambahkan Revisi ke model
  • Ubah Setelan model, termasuk lembar gaya yang digunakan oleh model.
  • Ekspor model ke file.
  • Hapus model.

Menambahkan API ke model

Anda dapat menambahkan API ke model dengan:

  • Mengimpor file WADL yang berisi definisi API
  • Mengimpor Spesifikasi OpenAPI (OpenAPI 2.0 atau 1.2)
  • Membuat resource dan metode secara manual

Anda juga dapat mengimpor file JSON SmartDocs ke model. File ini biasanya dibuat dengan mengekspor model yang ada terlebih dahulu, mengedit filenya, lalu mengimpor pembaruannya. Untuk mengetahui informasi selengkapnya, lihat "Mengekspor dan mengimpor model" di bawah.

Video: Tonton video singkat untuk mempelajari cara menambahkan API ke model SmartDocs dengan mengimpor Spesifikasi OpenAPI.

Mengimpor WADL

Setelah Anda berhasil membuat model, impor file WADL yang menjelaskan API Anda. Setiap kali mengimpor file WADL, Anda akan otomatis membuat revisi baru untuk model tersebut.

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Pilih model yang ingin Anda perbarui.
  4. Di bagian Operasi, pilih Impor.
  5. Pilih WADL di menu dropdown Choose Format pada halaman impor SmartDocs.
  6. Pilih File atau URL dari menu dropdown Upload Type.
    1. Jika Anda memilih File, cari file WADL.
    2. Jika Anda memilih URL, tentukan URL file WADL.
  7. Klik Import untuk mengimpornya ke model. Sekarang Anda dapat merender model.
  8. Anda akan dialihkan ke halaman informasi model tempat Anda kini dapat merender model.

Mengimpor Spesifikasi OpenAPI

Setelah berhasil membuat model, Anda dapat mengimpor Spesifikasi OpenAPI (sebelumnya Swagger). Edge mendukung OpenAPI versi 1.2 dan 2.0.

OpenAPI menggunakan file yang berisi objek JSON untuk mendeskripsikan API. Setiap kali mengimpor Spesifikasi OpenAPI, Anda akan otomatis membuat revisi baru untuk model tersebut.

Untuk mengimpor Spesifikasi OpenAPI:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Pilih model yang ingin Anda perbarui.
  4. Di bagian Operasi, pilih Impor.
  5. Pilih Swagger JSON atau Swagger YAML di menu dropdown Choose Format pada halaman impor SmartDocs.
  6. Pilih File atau URL pada menu dropdown Upload Type (Anda harus memilih URL untuk OpenAPI 1.2).
    1. Jika Anda memilih File, buka Spesifikasi OpenAPI.
    2. Jika Anda memilih URL, tentukan URL OpenAPI Specification.
  7. Klik Import untuk mengimpornya ke model.
  8. Anda akan dialihkan ke halaman informasi model tempat Anda kini dapat merender model.

Membuat resource dan metode secara manual

Jika tidak memiliki file WADL atau Spesifikasi OpenAPI yang mewakili API, Anda dapat menambahkan API secara manual ke model. Selain itu, jika menggunakan file WADL atau Spesifikasi OpenAPI untuk membuat model, Anda dapat menggunakan prosedur ini untuk mengedit API, termasuk menambahkan API baru, setelah mengimpor.

Untuk menambahkan API secara manual:

  1. Buat revisi baru untuk model.

    Saat membuat revisi, Anda menentukan satu jalur dasar dari semua API dalam model, yang berarti semua API dalam model berbagi jalur dasar yang sama. Misalnya, tentukan jalur dasar sebagai:

    https://myCompany.com/v1

    Saat Anda menambahkan resource ke model, resource tersebut akan memperluas jalur dasar.
  2. Tentukan satu atau beberapa resource untuk model. Jalur resource digabungkan dengan jalur dasar revisi model untuk menentukan URL lengkap resource. Misalnya, jika resource Anda menentukan jalur "/login", URL lengkap resource tersebut adalah:

    https://myCompany.com/v1/login
  3. Tentukan satu atau beberapa metode untuk setiap resource. Sebuah metode menentukan verb HTTP yang dapat dipanggil pada resource. Misalnya, untuk resource "/login", Anda mendukung POST untuk login dan DELETE untuk logout. Resource ini tidak mendukung kata kerja HTTP lainnya, seperti PUT atau GET. Karena itu, tentukan dua metode untuk sumber daya, satu untuk POST dan satu lagi untuk DELETE.

    Metode ini menggunakan URL resource dari resource induknya. Oleh karena itu, semua metode dengan URL yang sama ditentukan dalam satu resource di SmartDocs.

Sebagai aturan umum:

  • Buat model SmartDocs yang berbeda untuk setiap jalur dasar unik di API Anda.
  • Tentukan resource SmartDocs yang berbeda untuk setiap resource unik di API Anda.
  • Menentukan metode SmartDocs yang berbeda untuk setiap kata kerja HTTP yang didukung oleh resource.

Membuat revisi baru untuk sebuah model

Anda hanya dapat menambahkan resource ke revisi model yang sudah ada. Jika model sudah memiliki revisi, Anda dapat menambahkan resource. Jika modelnya baru dan tidak memiliki revisi, buat revisi baru.

Untuk membuat revisi baru pada model:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin diperbarui, pilih Add Revision di bagian Operations.
  4. Pada halaman Tambahkan Revisi API, masukkan informasi berikut:
    • Display Name: Nama revisi seperti yang muncul di portal.
    • ID Versi: ID singkat untuk revisi.
    • Deskripsi: Deskripsi revisi.
    • URL Dasar: URL dasar semua API dalam revisi model. Sebuah model dapat menggunakan URL dasar yang berbeda untuk setiap revisi. Misalnya, Anda menyertakan indikator versi di URL dasar. Untuk revisi model pertama, URL dasarnya adalah:
      https://myCompany.com/v1
      Untuk revisi berikutnya, URL dasarnya adalah:
      https://myCompany.com/v2
  5. Pilih Tambahkan Revisi. Anda akan dialihkan ke halaman revisi model. Sekarang Anda dapat menentukan resource pada model.

Menentukan resource

Resource menetapkan URL lengkap API. Saat menentukan resource, tentukan jalur resource yang akan digabungkan dengan URL dasar dalam revisi model untuk membuat URL lengkap resource.

Untuk menentukan resource:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda update, di bagian Operations, pilih API Revisions untuk melihat semua revisi dari suatu model.
  4. Pilih revisi yang akan diedit.
  5. Di halaman revisi, pilih Add Resource dari menu dropdown.
  6. Di halaman Add Resource, masukkan informasi berikut:
    • Nama Tampilan: Nama resource.
    • Jalur: Jalur resource, dimulai dengan "/". Nilai Path digabungkan dengan URL Dasar dari revisi model untuk membuat URL lengkap resource.
    • Deskripsi: Deskripsi resource.
    • Parameters: Secara opsional, masukkan objek JSON yang menentukan setiap parameter pada resource. Parameter tersebut dijelaskan di bawah.
  7. Pilih Add Resource. Anda akan dialihkan ke halaman model. Sekarang Anda dapat menetapkan metode pada resource.

Secara opsional, Anda dapat menambahkan parameter ke resource, seperti parameter template, kueri, dan header. Semua parameter resource diwarisi oleh metode apa pun yang ditetapkan pada resource tersebut. Oleh karena itu, jika Anda menetapkan parameter kueri pada resource, semua metode yang ditambahkan ke resource tersebut harus mendukung parameter kueri tersebut.

Atau, Anda dapat menentukan parameter pada suatu metode. Misalnya, metode POST mungkin mendukung parameter kueri yang tidak didukung oleh metode DELETE. Oleh karena itu, tambahkan parameter apa pun khusus untuk metode saat Anda menentukan metode tersebut, seperti yang dijelaskan di bawah ini.

Gambar berikut menampilkan halaman SmartDocs yang ada untuk Apigee Setujui atau Ignore Developer App API dengan setiap jenis parameter yang ditandai:

Setiap jenis parameter ditetapkan oleh objek JSON:

Jenis

Objek JSON

Catatan

Template

{
"dataType": "string",
"defaultValue": "",
"description": "Nama organisasi.",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

Parameter template selalu wajib ada, jadi tetapkan required ke true, dan hapus nilai ke defaultValue.

Nilai description akan muncul dalam pop-up saat pengguna mengarahkan kursor ke URL pada halaman SmartDocs.

Kueri

{
"dataType": "string",
"defaultValue": "",
"description": "Lokasi.",
"name": "w",
"required": true,
"type": "QUERY"
}

Parameter kueri yang diperlukan masih dapat menentukan defaultValue, tetapi sering kali tidak.

Untuk parameter kueri opsional, tetapkan required ke false dan tentukan nilai ke defaultValue.

Header

{
"dataType": "string",
"defaultValue": "application/json",
"description": "Tentukan sebagai <code>application/json</code>.",
"name": "Content-Type",
"required": true,
"type": " Anda"
}

Perhatikan cara menggunakan tag HTML dalam deskripsi.

Parameter template menentukan variabel di jalur resource. Misalnya, Anda menetapkan dua parameter template pada resource. Perhatikan bahwa setiap definisi parameter dalam array parameter dipisahkan oleh koma:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Anda kemudian bisa menggunakan parameter template dalam definisi Jalur resource, yang diapit dengan "{}". Misalnya, tetapkan jalur ke:

/login/{org_name}/{developer_email}

Di halaman SmartDocs API, pengguna harus mengedit URL untuk menentukan bagian org_name dan developer_email dari URL sebelum mereka dapat mengirimkan permintaan.

Mendefinisikan metode

Tentukan satu atau beberapa metode untuk setiap resource. Definisi metode menentukan kata kerja HTTP yang dapat dipanggil pada resource. Resource dapat memiliki satu metode yang ditentukan padanya, atau beberapa metode.

Sebagai bagian dari penentuan metode, tentukan parameter apa pun yang digunakan oleh metode, termasuk parameter kueri dan header. Lihat deskripsi di atas untuk referensi tentang informasi tentang cara menambahkan parameter ke metode.

Gambar berikut menampilkan halaman SmartDocs yang ada untuk Apigee Create Developer API dengan setiap area halaman ditandai dengan nilai yang sesuai yang Anda tetapkan saat menentukan metode:

Gambar berikutnya menampilkan halaman yang sama tetapi dengan Deskripsi Isi Permintaan dipilih:

Untuk menentukan metode:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda update, di bagian Operations, pilih API Revisions untuk melihat semua revisi dari suatu model.
  4. Pilih revisi yang akan diedit.
  5. Di halaman revisi, pilih Add Method dari menu dropdown untuk salah satu resource.
  6. Pada halaman Edit Method, masukkan informasi berikut:
    • Display Name: Nama API, yang juga menjadi judul halaman Drupal untuk API tersebut.
    • Deskripsi: Jelaskan API.
    • Metode Kata kerja: Jenis kata kerja HTTP.
    • Skema Keamanan: Tentukan mode autentikasi, jika ada, untuk metode tersebut. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi jenis autentikasi SmartDocs.
    • Jenis Konten: Jenis konten permintaan dan respons. Lihat bagian di bawah tentang cara mengonfigurasi berbagai metode autentikasi.
    • Parameter: (Opsional) Parameter kueri atau header apa pun untuk metode. Lihat deskripsi di atas untuk menambahkan parameter ke resource guna mengetahui informasi selengkapnya.
    • Meminta Dokumentasi Isi: (Opsional) Deskripsikan isi permintaan. Metode POST dan PUT mengambil isi permintaan. Anda dapat menggunakan area ini untuk mendeskripsikannya. Jika Anda menghilangkan nilai ini, link Description di bagian Isi Permintaan akan dihilangkan dari halaman SmartDocs yang dibuat.
    • Contoh Isi Permintaan: (Opsional) Menampilkan contoh isi permintaan, biasanya sebagai objek JSON atau sebagai XML. Untuk kata kerja POST dan PUT, Contoh Isi Permintaan diteruskan sebagai bagian dari setiap permintaan. Pengguna halaman SmartDocs mengedit contoh ini sebelum mengirimkan permintaan ke API. Jika Anda menghapus nilai ini, link Value di bagian Request Body akan dihilangkan dari halaman SmartDocs yang dibuat.
    • Tag: Array tag yang terkait dengan API. SmartDocs menggunakan tag untuk mengelompokkan API yang serupa. Misalnya, Anda dapat menerapkan tag "Statistik" ke semua API tentang statistik. Anda dapat mengelompokkan API dari berbagai resource dalam satu tag, jika semua API menggunakan tag yang sama.
  7. Pilih Add Method. Anda akan dialihkan ke halaman model. Sekarang Anda dapat merender dan memublikasikan metode Anda.

Merender model

Setelah menambahkan API ke model, Anda dapat merender model. Rendering mengonversi deskripsi model tentang API menjadi node Drupal. Saat rendering selesai, Anda akan memiliki satu node Drupal untuk setiap API, dengan setiap node Drupal terkait dengan sebuah halaman HTML.

Anda dapat memilih untuk merender seluruh model sekaligus, atau memilih API satu per satu untuk rendering.

Untuk merender model:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda render, pilih API Revisions di bagian Operations.
  4. Pilih revisi yang ingin dirender. Anda hanya dapat merender node dari satu revisi model.
  5. Pilih metode yang akan dirender.
  6. Pilih Render Nodes dari menu drop-down Update options.
  7. Klik Perbarui.
  8. Layar pemuatan akan muncul untuk melihat progres pada node Anda yang sedang dirender.
    Setelah node dirender, ID node Drupal untuk setiap API akan muncul di kolom Node Association pada model. Klik link di kolom Node Association untuk melihat node yang dirender.

Daripada memilih Render Nodes, Anda dapat memilih Render dan publish node untuk merender dan segera memublikasikan API sebagai node Drupal.

Memublikasikan node

Node tidak terlihat oleh pengguna portal hingga node dipublikasikan. Anda juga dapat memilih untuk memublikasikan node selama proses rendering. Jika memilih untuk tidak memublikasikan node, Anda harus memublikasikannya secara manual setelah rendering selesai.

Untuk memublikasikan node:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda publikasikan, pilih Revisi API di bagian Operasi.
  4. Pilih revisi yang ingin dipublikasikan. Anda hanya dapat memublikasikan node dari revisi model tunggal.
  5. Pilih metode yang akan dipublikasikan.
  6. Pilih node dalam revisi yang akan dipublikasikan.
  7. Pilih Publish Nodes dari dropdown opsi Update.
  8. Klik Perbarui.
  9. Buka node dengan memilih ID node di kolom Node Association.

Secara default, URL Drupal ke node API yang dipublikasikan berbentuk: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. Gunakan prosedur berikut untuk mengontrol bentuk URL:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Konfigurasi > Penelusuran dan metadata > Alias URL > Pola di menu administrasi Drupal.
  3. Di bagian Pattern for all SmartDocs Method path, tentukan cara Anda ingin membuat jalur.
  4. Pilih Save configuration.

Karena disimpan dalam cache di portal, Anda mungkin tidak akan melihat halaman model muncul segera setelah memublikasikannya. Jika perlu, Anda dapat menghapus cache HTML SmartDocs secara manual menggunakan prosedur berikut:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Configuration > SmartDocs di menu administrasi Drupal.
  3. Klik Rebuild SmartDocs model caches.

Membatalkan publikasi node

Anda dapat membatalkan publikasi node yang dipublikasikan kapan saja. Membatalkan publikasi node akan membuatnya tidak terlihat oleh pengguna portal.

Untuk membatalkan publikasi node:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda batalkan publikasinya, pilih Revisi API di bagian Operasi.
  4. Pilih revisi model node yang publikasinya ingin dibatalkan.
  5. Pilih node dalam revisi untuk membatalkan publikasi.
  6. Pilih Batalkan publikasi Node dari menu drop-down opsi Update.
  7. Klik Perbarui.

Melihat revisi model

Anda membuat revisi model baru dengan mengimpor file WADL baru atau Spesifikasi OpenAPI ke model yang sudah ada, atau dengan membuat revisi baru secara manual. Setelah membuat revisi baru, Anda dapat merender dan memublikasikan revisi tersebut, yang menggantikan node Drupal yang saat ini dipublikasikan.

Anda dapat merender dan memublikasikan node dari beberapa revisi secara bersamaan. Artinya, jika memiliki lima revisi dari sebuah model, Anda dapat memublikasikan node dari setiap atau semua revisi. Namun, memublikasikan API dalam satu model yang sama dengan node yang dipublikasikan dari model lain akan membatalkan publikasi versi lama API dan menggantinya dengan node dari API yang paling baru dipublikasikan.

Untuk melihat revisi model:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin diperbarui, pilih Revisi API di bagian Operasi.
  4. Pilih revisi model yang ingin dilihat.
  5. Render dan publikasikan node seperti yang dijelaskan di atas.

Mengedit node

Setelah merender node, Anda dapat mengeditnya menggunakan editor Drupal. Misalnya, Anda dapat mengedit kata kerja HTTP dan deskripsi API, atau menambahkan parameter kueri atau header baru ke API. Anda dapat mengedit node yang dibuat dari file WADL atau Spesifikasi OpenAPI, atau node yang dibuat secara manual.

Anda juga dapat mengedit file WADL atau Spesifikasi OpenAPI yang asli. Setelah selesai mengedit, impor file WADL atau Spesifikasi OpenAPI kembali ke model sebagai revisi baru, lalu render dan publikasikan perubahan seperti yang dijelaskan di atas.

Untuk mengedit node menggunakan editor Drupal:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Jelajahi node Drupal yang sesuai dengan dokumentasi API yang ingin Anda edit.
  3. Pilih Edit untuk menggunakan editor Drupal.
  4. Setelah pengeditan selesai, pilih Metode Pembaruan.

Atau, Anda dapat mengedit node dari model SmartDocs:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin diperbarui, pilih Revisi API di bagian Operasi.
  4. Pilih revisi model yang ingin dipublikasikan.
  5. Pilih Edit method di menu drop-down Operations untuk metode yang ingin Anda edit.

Untuk menghapus node:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin diperbarui, pilih Revisi API di bagian Operasi.
  4. Pilih revisi model yang ingin dipublikasikan.
  5. Pilih Delete method di menu dropdown Operations untuk metode tersebut.
    Perhatian: Menghapus node juga akan menghapus API dari model. Jika Anda hanya ingin membatalkan publikasi API agar tersembunyi dari pengguna portal, tetapi tidak ingin menghapusnya dari model, sebaiknya batalkan publikasi node seperti yang dijelaskan di atas.

Portal ini memiliki laporan bawaan yang menampilkan informasi tentang node yang dirender oleh model SmartDocs yang tidak lagi merujuk pada metode model yang valid. Akses laporan dengan memilih Reports di menu Drupal, lalu pilih laporan yang bernama SmartDocs status.

Mengekspor dan mengimpor model

SmartDocs memungkinkan Anda mengekspor model yang ada ke file. Misalnya, Anda dapat menentukan lingkungan produksi dan staging. Kemudian, lakukan semua pengeditan SmartDocs di lingkungan staging. Jika sudah siap merilis API, ekspor model staging dan impor ke model produksi.

Mengimpor model akan membuat revisi baru untuk model tersebut. SmartDocs mencoba mencocokkan API yang ada dalam model dengan API yang diimpor. Jika SmartDocs mendeteksi kecocokan, impor akan memperbarui node Drupal yang sesuai dengan API yang ada. Jika SmartDocs tidak mendeteksi kecocokan, proses impor akan membuat node Drupal baru untuk API.

Misalnya, Anda memiliki POST API yang sesuai dengan node Drupal dengan ID 91. Kemudian, impor model dan SmartDocs akan mendeteksi kecocokan POST API dalam model yang diimpor dengan POST API yang ada. Setiap update ke POST API akan mengupdate node Drupal 91. Jika tidak mendeteksi kecocokan, SmartDocs akan membuat node Drupal baru dengan ID baru.

Drupal melakukan pencocokan menggunakan karakteristik API berikut:

  • internalName: Nama model internal.
  • httpMethod: Metode HTTP API, seperti: GET, PUT, POST, atau DELETE.
  • resourcePath: Jalur resource.
  • query params: Parameter kueri apa pun yang digunakan oleh API.

Jika keempat karakteristik API yang diimpor cocok dengan API yang ada dalam model, SmartDocs akan memperbarui node Drupal yang ada.

Model yang diekspor diwakili oleh satu objek JSON dengan entri untuk resource dan metode. Artinya, Anda dapat mengedit model yang diekspor untuk mengubah resource atau metode, lalu mengimpor ulang model tersebut. Jika Anda mengedit objek JSON, jangan ubah kolom berikut:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

Untuk mengekspor model:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin diekspor, pilih Export di bagian Operations.
  4. Pilih jenis file ekspor sebagai SmartDocs JSON.
  5. Klik Ekspor.
  6. Anda diminta untuk menyimpan file ke disk atau membukanya di editor.

Untuk mengimpor model:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda impor, pilih Import di bagian Operations.
  4. Pilih SmartDocs JSON di dropdown Choose Format.
  5. Pilih File atau URL di bagian Jenis Upload:
    1. Jika Anda memilih File, cari file JSON.
    2. Jika Anda memilih URL, tentukan URL file JSON SmartDocs.
  6. Klik Import untuk mengimpornya ke model.
  7. Anda akan dialihkan ke halaman informasi model tempat Anda kini dapat merender model. Perlu diketahui bahwa impor akan membuat revisi baru untuk model.
  8. Merender dan memublikasikan node.

Mengedit template SmartDocs

Template SmartDocs menentukan bagaimana node Drupal Anda muncul di layar. Setiap model SmartDocs dapat menggunakan template default yang sama atau Anda dapat menyesuaikan secara manual template yang digunakan untuk setiap model.

Template SmartDocs berisi file template yang dikodekan sebagai file Handlebars .hbr, file CSS, dan file JavaScript. Dengan Setang, sebagian besar konten digerakkan oleh variabel menggunakan ekspresi setang tersemat, seperti &123;&123;body}}. Daftar ekspresi Handlebar yang ada disediakan dalam komentar di bagian atas file. Untuk mengetahui informasi tentang cara menggunakan Handlebar untuk menyesuaikan template, lihat http://handlebarsjs.com.

Bagian berikut menjelaskan cara mengupload file template SmartDocs kustom untuk digunakan oleh semua model baru atau saat Anda mengimpor API baru ke dalam model yang ada, cara memulihkan file template SmartDocs default yang asli, dan cara memodifikasi template SmartDocs untuk masing-masing model.

Mengupload file template SmartDocs kustom

Anda dapat mengupload file template SmartDocs kustom, sebagai file Handlebars .hbr, untuk digunakan sebagai template default saat membuat model baru atau mengimpor API baru ke model yang sudah ada.

Jika ingin menggunakan file template SmartDocs default sebagai titik awal saat membuat file template SmartDocs kustom, Anda dapat mendownload salinannya dari: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Untuk mengupload file template SmartDocs kustom:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Configuration > SmartDocs di menu administrasi Drupal.
  3. Luaskan area Setelan Lanjutan di halaman.
  4. Di bagian Upload Custom method template, klik Choose File, lalu buka file .hbr Handlebars.
  5. Klik Upload.
  6. Klik Save configuration.

Memulihkan file template SmartDocs default

Anda dapat memulihkan file template SmartDocs default. Setelah dipulihkan, file template SmartDocs default akan digunakan saat membuat model baru atau mengimpor API baru ke dalam model yang sudah ada.

Untuk memulihkan file template SmartDocs default:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Configuration > SmartDocs di menu administrasi Drupal.
  3. Luaskan area Setelan Lanjutan di halaman.
  4. Di bagian Upload template metode kustom, klik Remove di samping file template SmartDocs kustom.
  5. Klik Save configuration.

Memodifikasi template SmartDocs untuk setiap model

Anda dapat memodifikasi template yang digunakan untuk setiap model.

Untuk memodifikasi template model individual:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda edit, pilih Settings di bagian Operations.
  4. Di area Method Template, edit template sesuai kebutuhan.
  5. Klik Simpan template.
  6. Jelajahi node Drupal. Anda akan melihat perubahan template di halaman.

Mengonfigurasi jenis autentikasi SmartDocs

API yang ditetapkan di SmartDocs dapat bersifat terbuka, yang berarti tidak diperlukan kredensial autentikasi untuk mengaksesnya, atau aman. API aman mengharuskan Anda meneruskan kredensial saat melakukan panggilan ke API.

Untuk API yang aman, SmartDocs mendukung jenis autentikasi berikut:

  • Autentikasi dasar - Meneruskan kredensial autentikasi dasar sebagai pasangan nama pengguna dan sandi. Jika Anda tidak menentukan untuk menggunakan OAuth sebagai jenis kredensial, API akan menggunakan autentikasi dasar secara default.
  • OAuth 2.0 - Penyedia layanan pihak ketiga mengautentikasi kredensial pengguna, memastikan bahwa pengguna memiliki otorisasi ke API, lalu mengeluarkan token akses. Saat Anda membuat permintaan SmartDocs ke API yang dilindungi, SmartDocs akan membuat permintaan tersebut dan mengirimkannya ke penyedia layanan. Penyedia layanan kemudian memvalidasi token dan memastikannya belum habis masa berlakunya.
  • Token kustom - Teruskan nilai token sebagai header atau parameter kueri ke setiap permintaan.

Untuk setiap jenis autentikasi, Anda membuat skema keamanan yang menetapkan karakteristik autentikasi. Misalnya, untuk autentikasi token kustom, skema keamanan menentukan cara token diteruskan (header, param query, body param) dan nama token tersebut.

Skema keamanan dikaitkan dengan revisi model tertentu. Oleh karena itu, jika membuat revisi baru dari sebuah model, Anda harus menentukan ulang skema keamanan untuk revisi tersebut

Dalam file WADL, Anda menentukan apakah API memerlukan autentikasi menggunakan tag Apigee <apigee:authentication>, seperti yang ditunjukkan di bawah ini:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

Jika API terbuka, tetapkan atribut required ke false.

Perhatikan bahwa Anda tidak dapat menentukan jenis autentikasi di file WADL. Anda melakukannya dengan mengedit node di Drupal. Untuk mengetahui informasi selengkapnya tentang file WADL, lihat Referensi WADL.

Pada halaman API di Drupal, SmartDocs menambahkan tombol berikut agar pengguna dapat menentukan kredensial autentikasi dasar:

Jika Anda mengedit node untuk menetapkan jenis autentikasi ke OAuth, SmartDocs akan menambahkan tombol berikut ke halaman:

Untuk token kustom, SmartDocs menambahkan:

Mengonfigurasi autentikasi dasar

Jika menggunakan autentikasi dasar dengan API, Anda hanya perlu menetapkan tag <apigee:authentication> di file WADL yang Anda gunakan untuk membuat model.

Untuk menerapkan autentikasi dasar ke metode yang dibuat dari sumber selain file WADL:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang diinginkan, pilih Revisi API di bagian Operasi.
  4. Untuk revisi model yang ingin Anda edit, pilih Security Settings di bagian Operations.
  5. Pilih Add Security Scheme.
  6. Tentukan nama skema keamanan.
  7. Pilih Dasar sebagai Jenis.
  8. Pilih Kirim.
  9. Untuk setiap metode dalam model, edit metode tersebut untuk menetapkan Skema Keamanan ke skema dasar Anda.
    1. Pilih Konten > SmartDocs di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih Revisi API di bagian Operasi.
    3. Untuk revisi model yang ingin diedit, pilih Revision Details di bagian Operations.
    4. Pilih Edit Method untuk API yang ingin Anda edit.
    5. Pilih Security Scheme untuk API.
    6. Simpan API.

Mengonfigurasi autentikasi OAuth 2.0

Anda dapat mengonfigurasi model untuk menggunakan OAuth 2.0 di SmartDocs, bukan autentikasi dasar default. Anda mengonfigurasi OAuth di dua lokasi:

  1. Buat skema keamanan untuk setiap revisi model di bagian Setelan Keamanan untuk revisi tersebut.
  2. Tentukan Client ID dan Rahasia Klien untuk semua revisi model di bagian Settings untuk model tersebut.

Untuk mengaktifkan OAuth:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang diinginkan, pilih Revisi API di bagian Operasi.
  4. Untuk revisi model yang ingin Anda edit, pilih Security Settings di bagian Operations.
  5. Pilih Add Security Scheme.
  6. Tentukan nama skema keamanan.
  7. Pilih OAuth 2.0 sebagai Jenis.
  8. Tetapkan Grant Type.
  9. Masukkan nilai di kolom URL Otorisasi. URL Otorisasi digunakan untuk mendapatkan token akses.
  10. Tetapkan Authorization Verb sebagai GET atau POST.
  11. Masukkan URL Token Akses. URL Token Akses adalah URL yang digunakan untuk menukar token permintaan dengan token akses.
  12. Masukkan nama parameter Access Token.
  13. Gunakan In untuk menentukan cara meneruskan token: Header, Query, atau Body.
  14. Tetapkan Cakupan OAuth.
  15. Pilih Kirim.
  16. Pilih Konten > SmartDocs di menu administrasi Drupal.
  17. Untuk model, pilih Settings di drop-down Operations.
  18. Masukkan nilai di Client ID dan Rahasia Klien.
  19. Pilih Save template authentication settings.
  20. Untuk setiap metode dalam model, edit metode tersebut untuk menetapkan Skema Keamanan ke skema keamanan OAuth Anda.
    1. Pilih Konten > SmartDocs di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih Revisi API di bagian Operasi.
    3. Untuk revisi model yang ingin diedit, pilih Revision Details di bagian Operations.
    4. Pilih Edit Method untuk API yang ingin Anda edit.
    5. Pilih Security Scheme untuk API.
    6. Simpan API.

Mengonfigurasi autentikasi token kustom

Anda dapat mengonfigurasi model untuk menggunakan autentikasi token kustom.

Untuk mengaktifkan token kustom:

  1. Login ke portal Anda sebagai pengguna yang memiliki hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang diinginkan, pilih Revisi API di bagian Operasi.
  4. Untuk revisi model yang ingin Anda edit, pilih Security Settings di bagian Operations.
  5. Pilih Add Security Scheme.
  6. Tentukan nama skema keamanan.
  7. Pilih Apikey sebagai Jenis.
  8. Tetapkan Param Name yang berisi token.
  9. Gunakan In untuk menentukan cara meneruskan token: Header, Query, atau Body.
  10. Pilih Kirim.
  11. Untuk setiap metode dalam model, edit metode tersebut untuk menetapkan Skema Keamanan ke skema token Anda.
    1. Pilih Konten > SmartDocs di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih Revisi API di bagian Operasi.
    3. Untuk revisi model yang ingin diedit, pilih Revision Details di bagian Operations.
    4. Pilih Edit Method untuk API yang ingin Anda edit.
    5. Pilih Security Scheme untuk API.
    6. Simpan API.

Menghapus model

Saat Anda menghapus model (Content > SmartDocs, Delete di kolom Operations di Drupal), model tersebut akan dihapus dari organisasi Edge Anda. Artinya, jika portal lain mereferensikan model, model tersebut tidak lagi tersedia. Untuk informasi selengkapnya, lihat Tentang model dan template SmartDoc.