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:

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

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

Edge management API adalah RESTful API yang memungkinkan Anda mengakses Layanan API menggunakan klien HTTP apa pun. Apigee menggunakan SmartDocs dalam membuat dokumentasi interaktif untuk Edge Management API. Lihat dokumentasi API 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, 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 target tiruan OpenAPI Specification, 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 resource ini ditampilkan:
  3. Klik Send this request.
  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 dengan 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 berkaitan 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. Tambahkan 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, baik sebelum maupun 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 file tersebut ke model sebagai revisi baru, lalu render dan publikasikan perubahan Anda.
  7. Aktifkan TLS. Karena SmartDocs dapat mengirim kredensial autentikasi ke backend sebagai bagian dari permintaan ke API Anda, Anda harus mengaktifkan TLS di portal untuk memastikan bahwa kredensial tersebut aman. Dalam lingkungan pengujian dan produksi portal, Apigee menyediakan sertifikat TLS yang diperlukan untuk membuat permintaan https://. Namun, sebelum mengaktifkan portal, Anda harus mendapatkan sertifikat TLS sendiri dan mengaktifkan TLS. Untuk mengetahui 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 mendefinisikan 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 lain. Setiap instance portal tampak berisi modelnya sendiri, tetapi semuanya benar-benar mereferensikan model sumber. Jika Anda mengedit API di developer, model akan diperbarui dan perubahannya akan muncul dalam 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 (yang diatur oleh Handlebar dan file CSS) disimpan dalam setiap instance portal. Jadi, secara teoritis, setiap portal dapat menggunakan template unik untuk setiap model. Namun, salah satu kemudahan dari framework rendering adalah bahwa template default (baik default Apigee maupun template yang Anda berikan) diterapkan secara otomatis 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 menerapkan SmartDocs sebagai modul Drupal kustom. Gunakan prosedur berikut untuk mengonfigurasi modul SmartDocs.

Untuk mengonfigurasi modul SmartDocs:

  1. Login ke portal Anda sebagai pengguna dengan 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 -> Permissions dan pastikan "Lakukan tugas administrasi untuk modul SmartDocs" untuk peran "Administrator" diaktifkan.
  7. Pilih Configuration > Dev Portal di menu administrasi Drupal.
  8. Setel Connection Timeout dan Request Timeout ke 16 detik.
  9. Simpan konfigurasi.
  10. Konfigurasikan setelan URL:
    1. Pilih Konfigurasi > Penelusuran dan metadata > Alias URL > Setelan dari menu Drupal.
    2. Tetapkan Maximum alias length dan Maximum component length ke 255.
    3. Perluas Tanda baca.
    4. Untuk setelan Kurung kurawal kiri ({) dan Kurung kurawal kanan (}), pilih Tidak ada tindakan (jangan ganti).
    5. Klik Save configuration.
  11. Jika portal developer Anda terekspos ke pengguna dalam jaringan internal tanpa akses ke internet atau jika subset 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. Update 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 dalam organisasi Edge Anda sebagai sumber untuk struktur API. Untuk informasi selengkapnya, lihat Tentang model dan template SmartDoc.

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > 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 sudah ada terlebih dahulu, mengedit filenya, lalu mengimpor updatenya. Untuk 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 berhasil membuat model, impor file WADL yang menjelaskan API Anda. Setiap kali mengimpor file WADL, Anda akan otomatis membuat revisi model baru.

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Pilih model yang ingin diperbarui.
  4. Di bagian Operasi, pilih Impor.
  5. Pilih WADL di dropdown Pilih 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 dari model.

Untuk mengimpor Spesifikasi OpenAPI:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Pilih model yang ingin diperbarui.
  4. Di bagian Operasi, pilih Impor.
  5. Pilih Swagger JSON atau Swagger YAML di menu dropdown Choose Format di halaman impor SmartDocs.
  6. Pilih File atau URL di menu dropdown Upload Type (Anda harus memilih URL untuk OpenAPI 1.2).
    1. Jika Anda memilih File, lihat ke OpenAPI Specification.
    2. Jika Anda memilih URL, tentukan URL dari 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 ke model secara manual. 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 diimpor.

Untuk menambahkan API secara manual:

  1. Buat revisi baru dari model.

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

    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 menetapkan 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. Metode menentukan verb HTTP yang bisa 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 untuk DELETE.

    Metode ini menggunakan URL resource dari resource induknya. Oleh karena itu, semua metode dengan URL yang sama didefinisikan 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.
  • Tentukan metode SmartDocs yang berbeda untuk setiap kata kerja HTTP yang didukung oleh resource.

Membuat revisi baru dari model

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

Untuk membuat revisi baru dari model:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda perbarui, 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 dari 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 menentukan URL lengkap API. Saat menentukan resource, Anda menentukan jalur resource, yang digabungkan dengan URL dasar dalam revisi model untuk membuat URL lengkap resource.

Untuk menentukan resource:

  1. Login ke portal Anda sebagai pengguna dengan 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 maket untuk melihat semua revisi dari suatu model.
  4. Pilih revisi yang akan diedit.
  5. Pada halaman revisi, pilih Tambahkan Referensi dari menu dropdown.
  6. Di halaman Add Resource, masukkan informasi berikut:
    • Nama Tampilan: Nama resource.
    • Path: Jalur resource, dimulai dengan "/". Nilai Path digabungkan dengan URL Dasar revisi model untuk membuat URL lengkap resource.
    • Deskripsi: Deskripsi resource.
    • Parameters: Secara opsional, masukkan objek JSON yang menentukan setiap parameter pada resource. Parameter ini dijelaskan di bawah.
  7. Pilih Tambahkan Resource. Anda akan dialihkan ke halaman model. Kini Anda dapat menentukan 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 metode. Misalnya, metode POST mungkin mendukung parameter kueri yang tidak didukung oleh metode DELETE. Oleh karena itu, tambahkan parameter apa pun khusus untuk metode tersebut saat Anda menentukan metode, seperti yang dijelaskan di bawah.

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

Setiap jenis parameter ditentukan oleh objek JSON:

Type

Objek JSON

Catatan

Template

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

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

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

Kueri

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

Parameter kueri yang diperlukan tetap 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": "HEADER"
}

Perhatikan bagaimana Anda dapat menggunakan tag HTML dalam deskripsi.

Parameter template menentukan variabel di jalur resource. Misalnya, Anda menetapkan dua parameter template pada resource. Perhatikan bagaimana setiap definisi parameter dalam array parameter dipisahkan dengan 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 selanjutnya dapat 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 menetapkan kata kerja HTTP yang bisa dipanggil pada resource. Resource dapat memiliki satu metode yang ditentukan, 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 resource guna mengetahui 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 terkait yang Anda tetapkan saat menentukan metode:

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

Untuk menentukan metode:

  1. Login ke portal Anda sebagai pengguna dengan 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 maket untuk melihat semua revisi dari suatu model.
  4. Pilih revisi yang akan diedit.
  5. Pada halaman revisi, pilih Add Method dari menu dropdown untuk salah satu resource.
  6. Di halaman Metode Edit, masukkan informasi berikut:
    • Display Name: Nama API, yang juga menjadi judul halaman Drupal untuk API.
    • Deskripsi: Jelaskan API.
    • Metode Verb: 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 mengonfigurasi berbagai metode autentikasi.
    • Parameter: (Opsional) Parameter header atau kueri apa pun untuk metode. Lihat deskripsi di atas untuk menambahkan parameter ke resource untuk 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 menghapus nilai ini, link Description di bagian Isi Permintaan dihilangkan dari halaman SmartDocs yang dihasilkan.
    • Contoh Isi Permintaan: (Opsional) Tampilkan contoh isi permintaan, biasanya sebagai objek JSON atau XML. Untuk kata kerja POST dan PUT, Contoh Isi Permintaan diteruskan sebagai bagian dari setiap permintaan. Pengguna halaman SmartDocs mengedit contoh ini sebelum mereka mengirimkan permintaan ke API. Jika Anda menghapus nilai ini, link Value di bagian Request Body akan dihilangkan dari halaman SmartDocs yang dihasilkan.
    • 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 semuanya menggunakan tag yang sama.
  7. Pilih Add Method. Anda akan dialihkan ke halaman model. Sekarang Anda dapat merender dan memublikasikan metode.

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, di mana setiap node Drupal berkaitan dengan sebuah halaman HTML.

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

Untuk merender model:

  1. Login ke portal Anda sebagai pengguna dengan 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 Anda render. Anda hanya dapat merender node dari revisi tunggal 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 bawah kolom Node Association pada model. Klik link di kolom Node Association untuk melihat node yang dirender.

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

Memublikasikan node

Node tidak terlihat oleh pengguna portal hingga node tersebut 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 dengan 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 tunggal model.
  5. Pilih metode yang akan dipublikasikan.
  6. Pilih node dalam revisi yang akan dipublikasikan.
  7. Pilih Publish Nodes dari menu dropdown Update opsi.
  8. Klik Perbarui.
  9. Buka node dengan memilih ID node di bagian 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 dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Configuration > Search and metadata > URL alias > Patterns di menu administrasi Drupal.
  3. Di bagian Pattern for all SmartDocs Method path, tentukan cara Anda ingin membuat jalur.
  4. Pilih Save configuration.

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

  1. Login ke portal Anda sebagai pengguna dengan 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. Jika publikasi node dibatalkan, node tidak akan terlihat oleh pengguna portal.

Untuk membatalkan publikasi node:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang tidak ingin Anda publikasikan, 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 dapat membuat revisi model baru dengan mengimpor file WADL baru atau Spesifikasi OpenAPI ke model yang ada, atau dengan membuat revisi baru secara manual. Setelah membuat revisi baru, Anda dapat merender dan memublikasikan revisi, yang menggantikan node Drupal yang saat ini dipublikasikan.

Anda dapat merender dan memublikasikan node dari beberapa revisi secara bersamaan. Artinya, jika memiliki lima revisi model, Anda dapat memublikasikan node dari salah satu 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 versi dari API yang terakhir dipublikasikan.

Untuk melihat revisi model:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda update, pilih API revisions di bagian Operations.
  4. Pilih revisi model yang ingin Anda lihat.
  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 verb HTTP dan deskripsi API, atau menambahkan parameter header atau kueri 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 asli atau Spesifikasi OpenAPI. Setelah selesai mengedit, impor kembali file WADL atau Spesifikasi OpenAPI ke model sebagai revisi baru, lalu render dan publikasikan perubahan Anda seperti yang dijelaskan di atas.

Untuk mengedit node menggunakan editor Drupal:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Cari 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 dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda update, pilih API revisions di bagian Operations.
  4. Pilih revisi model yang ingin Anda publikasikan.
  5. Pilih Edit method di dropdown Operations untuk metode yang ingin Anda edit.

Untuk menghapus node:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda update, pilih API revisions di bagian Operations.
  4. Pilih revisi model yang ingin Anda publikasikan.
  5. Pilih Delete method pada menu dropdown Operations untuk metode tersebut.
    Perhatian: Menghapus node juga akan menghapus API dari model. Jika hanya ingin membatalkan publikasi API agar disembunyikan 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 apa pun yang dirender oleh model SmartDocs yang tidak lagi merujuk pada metode model yang valid. Akses laporan dengan memilih Reports pada 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, Anda akan membuat semua hasil edit SmartDocs di lingkungan staging. Jika sudah siap merilis API, Anda dapat mengekspor model staging dan mengimpornya ke model produksi.

Mengimpor model akan membuat revisi baru dari 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, impor akan membuat node Drupal baru untuk API.

Misalnya, Anda memiliki POST API yang sesuai dengan node Drupal dengan ID 91. Kemudian, Anda mengimpor model dan SmartDocs akan mendeteksi kecocokan POST API dalam model yang diimpor dengan POST API yang ada. Setiap update pada POST API akan mengupdate node Drupal 91. Jika SmartDocs tidak mendeteksi kecocokan, node Drupal baru akan dibuat 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.
  • parameter kueri: Parameter kueri apa pun yang digunakan oleh API.

Jika keempat karakteristik API yang diimpor cocok dengan API yang ada dalam model, SmartDocs akan mengupdate 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
  • ModifyTime
  • apiRevisionId
  • resourceId

Untuk mengekspor model:

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

Untuk mengimpor model:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda impor, pilih Impor di bagian Operasi.
  4. Pilih SmartDocs JSON di dropdown Pilih 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. Perhatikan bahwa impor akan membuat revisi baru dari model tersebut.
  8. Render dan publikasikan 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 template yang digunakan secara manual untuk setiap model.

Template SmartDocs menyertakan file template yang dikodekan sebagai file .hbr Handlebars, file CSS, dan file JavaScript. Dengan Handlebar, sebagian besar konten berbasis variabel menggunakan ekspresi setang yang disematkan, seperti &123;&123;body}}. Daftar ekspresi Handlebar yang ada diberikan dalam komentar di bagian atas file. Untuk mengetahui informasi tentang penggunaan Handlebars untuk menyesuaikan template Anda, 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 model yang ada, cara memulihkan file template SmartDocs default asli, dan cara memodifikasi template SmartDocs untuk tiap model.

Mengupload file template SmartDocs kustom

Anda dapat mengupload file template SmartDocs kustom, sebagai file .hbr Handlebars, 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 salinan dari: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Untuk mengupload file template SmartDocs kustom:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Configuration > SmartDocs di menu administrasi Drupal.
  3. Luaskan area Setelan Lanjutan di halaman tersebut.
  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 dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Configuration > SmartDocs di menu administrasi Drupal.
  3. Luaskan area Setelan Lanjutan di halaman tersebut.
  4. Di bagian Upload custom method template, klik Remove di samping file template SmartDocs kustom.
  5. Klik Save configuration.

Memodifikasi template SmartDocs untuk setiap model

Anda dapat mengubah template yang digunakan untuk setiap model.

Untuk memodifikasi template model individual:

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

Mengonfigurasi jenis autentikasi SmartDocs

API yang ditentukan 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 itu dan mengirimkannya ke penyedia layanan. Penyedia layanan kemudian akan memvalidasi token dan memastikan bahwa token tersebut belum habis masa berlakunya.
  • Token kustom - Meneruskan nilai token sebagai header atau parameter kueri ke setiap permintaan.

Untuk setiap jenis autentikasi, Anda membuat skema keamanan yang menentukan karakteristik autentikasi. Misalnya, untuk autentikasi token kustom, skema keamanan menentukan cara token diteruskan (header, parameter kueri, parameter isi) dan nama token.

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

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

<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 otentikasi dalam file WADL. Anda dapat 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 untuk memungkinkan pengguna 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 dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang diinginkan, pilih APIRevisis di bagian Operations.
  4. Untuk revisi model yang ingin Anda edit, pilih Setelan Keamanan di bagian Operasi.
  5. Pilih Add Security Scheme.
  6. Tentukan name 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 Content > SmartDocs di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih APIRevisis di bagian Operations.
    3. Untuk revisi model yang ingin Anda edit, pilih Detail Revisi di bagian Operasi.
    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 agar 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.

Untuk mengaktifkan OAuth:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Content > 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 Setelan Keamanan di bagian Operasi.
  5. Pilih Add Security Scheme.
  6. Tentukan name 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 Content > SmartDocs di menu administrasi Drupal.
  17. Untuk model, pilih Settings dari drop-down Operations.
  18. Masukkan nilai di Client ID dan Client Secret.
  19. Pilih Simpan setelan autentikasi template.
  20. Untuk setiap metode dalam model, edit metode tersebut untuk menetapkan Skema Keamanan ke skema keamanan OAuth Anda.
    1. Pilih Content > SmartDocs di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih APIRevisis di bagian Operations.
    3. Untuk revisi model yang ingin Anda edit, pilih Detail Revisi di bagian Operasi.
    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 agar menggunakan autentikasi token kustom.

Untuk mengaktifkan token kustom:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa pembuatan konten atau admin.
  2. Pilih Content > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang diinginkan, pilih APIRevisis di bagian Operations.
  4. Untuk revisi model yang ingin Anda edit, pilih Setelan Keamanan di bagian Operasi.
  5. Pilih Add Security Scheme.
  6. Tentukan name skema keamanan.
  7. Pilih Apikey sebagai Type.
  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 Content > SmartDocs di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih APIRevisis di bagian Operations.
    3. Untuk revisi model yang ingin Anda edit, pilih Detail Revisi di bagian Operasi.
    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 (Konten > 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 mengetahui informasi selengkapnya, lihat Tentang model dan template SmartDoc.