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 memudahkan Dokumentasi API yang sepenuhnya interaktif. Dokumentasi interaktif memungkinkan pengguna portal dapat:

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

Dengan membuat dokumentasi interaktif tentang 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. Apigee menggunakan SmartDocs guna membuat dokumentasi interaktif untuk pengelolaan Edge Compute Engine 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 developer portal.

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

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

Hello World API dibuat dari target tiruan OpenAPI Spesifikasi, 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.

Pelajari Hello World API:

  1. Klik Hello World API. Halaman ringkasan Hello World API ditampilkan:
  2. Klik Lihat afirmasi API. SmartDocs untuk referensi ini adalah 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 Permintaan untuk melihat permintaan, atau cURL untuk melihat panggilan cURL yang sesuai.

Cara mendokumentasikan API menggunakan SmartDocs

SmartDocs merepresentasikan API Anda dengan menggunakan model, yang berisi semua model 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 ke halaman dokumentasi di portal.

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

  1. Konfigurasikan modul SmartDocs Drupal di portal.
  2. Buat model SmartDocs.
  3. Menambahkan API ke model dari file WADL, OpenAPI (sebelumnya Swagger) spesifikasi, atau secara manual.
  4. Render model sebagai kumpulan node Drupal. Setiap node Drupal berisi informasi tentang satu API. Misalnya, jika resource dalam API Anda mendukung POST dan permintaan PUT, SmartDocs 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 atau sesudah Anda memublikasikannya. Anda dapat edit node Drupal menggunakan editor Drupal atau dengan mengedit file WADL asli, atau Spesifikasi OpenAPI. Setelah Anda selesai mengedit file WADL atau Spesifikasi OpenAPI, impor kembali ke model sebagai revisi baru, lalu render dan publikasikan perubahan.
  7. Aktifkan TLS. Karena SmartDocs dapat mengirim kredensial autentikasi ke backend sebagai bagian dari pembuatan permintaan ke API, 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 Anda aktif di portal Anda, Anda harus mendapatkan sertifikat TLS Anda sendiri dan mengaktifkan TLS. Untuk informasi selengkapnya, lihat Menggunakan TLS pada portal.

Tentang model dan template SmartDoc

Saat Anda membuat model di portal, model tersebut benar-benar disimpan di Edge organisasi Anda, 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. Semua update pada API di dalam portal secara otomatis didorong kembali ke model sumber.

Disimpan di organisasi

Disimpan di Drupal

model

template

Node drupal dengan fungsi pengeditan

Misalkan Anda memiliki beberapa portal di organisasi (misalnya, dev, stage, dan produksi). Di Pantheon, Anda memindahkan portal dari satu lingkungan ke lingkungan lainnya. Setiap instance tampak berisi model sendiri, tetapi semuanya benar-benar merujuk ke resource model transformer. Jika Anda mengedit API di dev, model akan diperbarui, 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 Anda, dan template tersebut (diatur oleh Handlebar dan file CSS) disimpan dengan setiap instance portal. Jadi, secara teori setiap portal dapat menggunakan template unik untuk setiap model. Namun, salah satu kepraktisan framework rendering adalah template default (baik default Apigee atau template yang Anda berikan) diterapkan ke tiap 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 admin atau pembuatan konten.
  2. Pilih Modules di menu administrasi Drupal. Daftar semua modul Drupal yang terinstal akan muncul.
  3. Aktifkan modul SmartDocs.
  4. Simpan konfigurasi.
  5. Pilih Modul di menu admin Drupal.
  6. Pilih SmartDocs -> Izin dan memastikan bahwa "Melakukan administrasi untuk modul SmartDocs" untuk "Administrator" peran diaktifkan.
  7. Pilih Configuration > Dev Portal dalam administrasi Drupal Google Spreadsheet.
  8. Setel Connection Timeout dan Request Timeout ke 16 detik.
  9. Simpan konfigurasi.
  10. Konfigurasikan setelan URL:
    1. Pilih Configuration > Penelusuran dan metadata > Alias URL > Setelan dari menu Drupal.
    2. Setel Maksimum alias length dan Maksimum komponen panjangnya menjadi 255.
    3. Luaskan Tanda baca.
    4. Untuk Tanda kurung kurawal buka ({) dan Tanda kurung kurawal tutup (}) setelan, pilih No action (do not replace).
    5. Klik Simpan konfigurasi.
  11. Jika portal developer akan terekspos ke pengguna di jaringan internal tanpa akses ke internet atau jika sebagian API Anda berada di jaringan pribadi, konfigurasikan SmartDocs API URL proxy, sebagai berikut:
    1. Pilih Configuration > SmartDocs di Administrasi Drupal Google Spreadsheet.
    2. Luaskan Setelan Lanjutan.
    3. Perbarui kolom URL proxy SmartDocs sebagai berikut: <host>/smartdocs/v1/sendrequest.
      Bantuan inline harus memberikan nilai yang diperlukan untuk lingkungan Anda. Contoh:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      Setelan default kolom ini adalah https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Klik Simpan konfigurasi.

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

Tiap model menetapkan nama internal unik yang juga mendefinisikan URL dasar dari node Drupal yang dihasilkan. URL untuk 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 hapus.
  • resourcePath: Jalur resource.

Misalnya, jika Anda menentukan nama internal sebagai 'mymodel', URL untuk nama yang dibuat Node Drupal 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 akan disimpan di organisasi Edge Anda sebagai sumber untuk API karena ada berbagai struktur penetapan harga. Untuk informasi selengkapnya, lihat Tentang model SmartDoc dan template.

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDocs dalam administrasi Drupal Google Spreadsheet.
  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 akan ditampilkan. Nama internal 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 bisa menggunakan menu drop-down Operasi bx ke:

  • Impor file WADL yang mendeskripsikan API Anda atau tentukan URL OpenAPI Spesifikasi yang menjelaskan API Anda.
  • Menambahkan Revisi ke model
  • Ubah Settings model, termasuk style sheet yang digunakan oleh model transformer.
  • 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 dalam model. File ini biasanya dibuat oleh pertama-tama mengekspor model yang ada, mengedit file, lalu mengimpor pembaruannya. Untuk selengkapnya, lihat "Mengekspor dan mengimpor model" di bawah ini.

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 Anda mengimpor file WADL, Anda secara otomatis membuat revisi model yang baru.

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

Mengimpor OpenAPI Spesifikasi

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

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

Untuk mengimpor Spesifikasi OpenAPI:

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

Membuat resource secara manual yang berbeda

Jika tidak mempunyai file WADL atau Spesifikasi OpenAPI yang mewakili API, Anda dapat menambahkan API ke model Anda secara manual. Juga, jika Anda menggunakan file WADL atau Spesifikasi OpenAPI untuk membuat model, Anda bisa menggunakan prosedur ini untuk mengedit API, termasuk menambahkan API baru, setelah impor.

Untuk menambahkan API secara manual:

  1. Buat revisi model yang baru.

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

    https://myCompany.com/v1

    Jika 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 dari revisi model untuk menentukan URL lengkap sumber daya. Misalnya, jika sumber daya Anda menentukan jalur "/login", URL lengkap resource-nya adalah:

    https://myCompany.com/v1/login
  3. Tentukan satu atau beberapa metode untuk setiap resource. Sebuah metode menentukan kata kerja HTTP yang dapat dipanggil pada resource. Misalnya, untuk "/login" Anda mendukung POST untuk login dan DELETE untuk keluar. Resource ini tidak mendukung kata kerja HTTP lainnya, seperti PUT atau GET. Oleh karena itu, definisikan 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 ditentukan pada satu resource di SmartDocs.

Sebagai aturan umum:

  • Buat model SmartDocs yang berbeda untuk setiap jalur dasar yang 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 terhadap model

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

Untuk membuat revisi baru terhadap model:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang ingin Anda perbarui, pilih Tambahkan Revisi di bagian Operations.
  4. Di halaman Add API Revisi, masukkan informasi berikut:
    • Nama Tampilan: Nama revisi seperti yang muncul dalam portal.
    • ID Versi: ID singkat untuk revisi.
    • Deskripsi: Deskripsi revisi.
    • URL Dasar: URL dasar semua API dalam revisi model. J dapat menggunakan URL dasar yang berbeda untuk setiap revisi. Misalnya, Anda menyertakan versi di URL dasar. Untuk revisi model pertama, URL dasarnya adalah:
      https://myCompany.com/v1
      Untuk revisi berikutnya, URL dasarnya dapat berupa:
      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 Anda.

Untuk menentukan resource:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda perbarui, di bagian Operations, pilih API Revisi untuk melihat semua revisi model.
  4. Pilih revisi yang akan diedit.
  5. Pada halaman revisi, pilih Add Resource dari menu dropdown.
  6. Di halaman Add Resource, masukkan informasi berikut:
    • Display Name: Nama resource.
    • Path: Jalur resource, diawali dengan "/". Nilai dari Path digabungkan dengan URL Dasar revisi model untuk membuat URL lengkap dari resource.
    • Deskripsi: Deskripsi resource.
    • Parameter: Opsional, masukkan objek JSON yang menentukan setiap parameter pada resource. Parameter ini dijelaskan di bawah.
  7. Pilih Tambahkan Referensi. Anda akan dialihkan ke halaman model. Anda sekarang dapat menentukan metode pada resource.

Jika ingin, Anda dapat menambahkan parameter ke resource, seperti template, kueri, dan header parameter. Semua parameter resource diwarisi oleh metode apa pun yang ditentukan pada resource tersebut. Oleh karena itu, jika Anda mendefinisikan parameter kueri pada sumber daya, semua metode akan ditambahkan ke sumber daya 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 khusus untuk metode saat Anda mendefinisikan metode, seperti dijelaskan di bawah ini.

Gambar berikut menampilkan halaman SmartDocs yang ada untuk Apigee Setujui atau Cabut Aplikasi Developer dengan setiap jenis parameter ditandai:

Setiap jenis parameter ditentukan oleh objek JSON:

Jenis

Objek JSON

Catatan

Template

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

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

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

Kueri

{
"dataType": "string",
"defaultValue": "",
"description": "Lokasi.",
"name": "w",
"wajib diisi": benar,
"type": "QUERY"
}

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

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

Header

{
"dataType": "string",
"defaultValue": "application/json",
"description": "Tentukan sebagai <code>application/json</code>.",
"name": "Jenis-Konten",
"wajib": benar,
"type": "Header"
}

Perhatikan bagaimana Anda dapat menggunakan tag HTML dalam deskripsi.

Parameter template menentukan variabel di jalur resource. Misalnya, Anda mendefinisikan 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 kemudian dapat menggunakan parameter template dalam definisi Jalur resource, yang diapit dalam "{}". 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 di resource tersebut. Resource dapat memiliki satu metode yang ditentukan, atau beberapa metode.

Sebagai bagian dari penetapan metode, tetapkan parameter apa pun yang digunakan oleh metode, termasuk kueri dan parameter header. Lihat deskripsi di atas untuk referensi guna mendapatkan informasi tentang cara menambahkan parameter ke suatu metode.

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

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 admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang ingin Anda perbarui, di bagian Operations, pilih API Revisi untuk melihat semua revisi model.
  4. Pilih revisi yang akan diedit.
  5. Pada halaman revisi, pilih Add Method dari menu dropdown untuk salah satu resource tersebut.
  6. Di halaman Edit Method, masukkan informasi berikut:
    • Nama Tampilan: Nama API, yang juga menjadi judul API Halaman Drupal untuk API.
    • Deskripsi: Menjelaskan API.
    • Method Verb: Jenis kata kerja HTTP.
    • Skema Keamanan: Tentukan mode autentikasi, jika ada, untuk . Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi autentikasi SmartDocs jenis data.
    • Jenis Konten: Jenis konten permintaan dan respons. Lihat di bawah ini tentang cara mengonfigurasi berbagai metode otentikasi.
    • Parameter: (Opsional) Parameter header atau kueri apa pun untuk metode. Lihat deskripsi di atas untuk menambahkan parameter ke resource untuk mengetahui informasi selengkapnya.
    • Dokumentasi Badan Permintaan: (Opsional) Jelaskan isi permintaan. POSTING dan metode PUT mengambil isi permintaan. Anda dapat menggunakan area ini untuk mendeskripsikannya. Jika Anda menghilangkan nilai, link Description di bagian Isi Permintaan dihilangkan dari halaman SmartDocs yang dibuat.
    • Contoh Isi Permintaan: (Opsional) Menampilkan contoh isi permintaan, biasanya sebagai objek JSON atau XML. Untuk kata kerja POST dan PUT, Isi Permintaan Contoh diteruskan sebagai bagian dari setiap permintaan. Pengguna halaman SmartDocs, edit ini sebelum mereka mengirimkan permintaan ke API. Jika Anda menghilangkan nilai ini, Link Nilai di bagian Isi Permintaan dihilangkan dari bagian halaman SmartDocs yang dibuat.
    • Tag: Array tag yang terkait dengan API. SmartDocs menggunakan tag untuk mengelompokkan API serupa bersama-sama. Misalnya, Anda dapat menerapkan tag "Statistik" ke semua API tentang statistik. Anda dapat mengelompokkan API dari berbagai resource menggunakan satu tag. jika mereka menggunakan tag yang sama.
  7. Pilih Add Method. Anda akan dialihkan ke halaman model. Anda sekarang dapat merender dan memublikasikan metode Anda.

Merender model

Setelah menambahkan API ke model, Anda dapat merender model. Rendering mengonversi deskripsi API ke dalam node Drupal. Saat rendering selesai, Anda akan memiliki satu Drupal untuk setiap API, di mana setiap node Drupal sesuai dengan halaman HTML.

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

Untuk merender model:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang ingin Anda render, pilih Revisi API di bagian Operasional.
  4. Pilih revisi yang ingin Anda render. Anda hanya bisa merender {i>node<i} dari satu revisi dari model.
  5. Pilih metode untuk dirender.
  6. Pilih Render Nodes dari menu Update options.
  7. Klik Perbarui.
  8. Layar pemuatan akan muncul untuk melihat progres rendering node Anda.
    Setelah node dirender, ID node Drupal untuk setiap API akan muncul di bagian Pengaitan Node dari model. Klik link di Node Pengaitan untuk melihat node yang dirender.

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

Memublikasikan node

Node tidak terlihat oleh pengguna portal hingga dipublikasikan. Anda dapat memilih untuk memublikasikan node selama proses rendering. Jika Anda 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 admin atau pembuatan konten.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda publikasikan, pilih Revisi API di bagian Operasional.
  4. Pilih revisi yang ingin dipublikasikan. Anda hanya dapat memublikasikan node dari satu revisi model.
  5. Pilih metode yang akan dipublikasikan.
  6. Pilih node dalam revisi yang akan dipublikasikan.
  7. Pilih Publish Nodes dari menu Update options.
  8. Klik Perbarui.
  9. Buka node dengan memilih ID node di bagian 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 admin atau pembuatan konten.
  2. Pilih Configuration > Penelusuran dan metadata > Alias URL > Pola di menu administrasi Drupal.
  3. Di bagian Pattern for all SmartDocs Method path, tentukan cara yang Anda inginkan membuat jalur.
  4. Pilih Save configuration.

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

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Configuration > SmartDocs dalam administrasi Drupal Google Spreadsheet.
  3. Klik Rebuild SmartDocs model caches.

Membatalkan publikasi node

Anda dapat membatalkan publikasi node yang telah dipublikasikan kapan saja. Membatalkan publikasi node membuat node tidak terlihat pengguna portal.

Untuk membatalkan publikasi node:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDocs di menu administrasi Drupal.
  3. Untuk model yang ingin Anda batalkan publikasinya, pilih Revisi API di bagian Operasional.
  4. Pilih revisi model node yang ingin Anda batalkan publikasinya.
  5. Pilih node dalam revisi untuk membatalkan publikasi.
  6. Pilih Batalkan Publikasi Node dari menu Update options.
  7. Klik Perbarui.

Melihat revisi model

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

Anda bisa merender dan memublikasikan node dari beberapa revisi sekaligus. Artinya jika Anda memiliki lima revisi model, Anda dapat menerbitkan {i>node<i} dari salah satu atau semua revisi. Namun, memublikasikan API dalam satu model yang sama dengan node yang dipublikasikan dari model lain akan membatalkan publikasi API tersebut dan menggantinya dengan versi yang terakhir dipublikasikan Compute Engine API.

Untuk melihat revisi model:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang ingin Anda update, pilih Revisi API di bagian Operasional.
  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 kata kerja HTTP dan deskripsi API, atau menambahkan kueri atau parameter header baru ke API. Anda dapat mengedit node yang dibuat dari file WADL atau Spesifikasi OpenAPI, atau node yang secara manual

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

Untuk mengedit node menggunakan editor Drupal:

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

Untuk menghapus node:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang ingin Anda update, pilih Revisi API di bagian Operasional.
  4. Pilih revisi model yang ingin Anda publikasikan.
  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, Anda harus membatalkan publikasi simpul seperti yang dijelaskan di atas.

Portal ini memiliki laporan bawaan yang menampilkan informasi tentang node apa pun yang dirender oleh SmartDocs yang tidak lagi merujuk pada metode model yang valid. Akses laporan paling lambat memilih Laporan di menu Drupal, lalu memilih laporan bernama status node SmartDocs.

Mengekspor dan mengimpor model

SmartDocs memungkinkan Anda mengekspor model yang ada ke file. Sebagai contoh, Anda mungkin mendefinisikan lingkungan production dan staging. Kemudian, Anda dapat membuat semua pengeditan SmartDocs dalam staging lingkungan fleksibel App Engine. Jika Anda sudah siap merilis API, ekspor model staging dan impor ke dalam model production.

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

Misalnya, Anda memiliki POST API yang sesuai dengan node Drupal dengan ID 91. Anda kemudian mengimpor model dan SmartDocs mendeteksi kecocokan POST API dalam model yang diimpor POST API. Semua update pada POST API kemudian update node Drupal 91. Jika SmartDocs tidak mendeteksi cocok, maka akan membuat node Drupal baru dengan ID baru.

Drupal melakukan pencocokan dengan menggunakan karakteristik API berikut:

  • internalName: Nama model internal.
  • httpMethod: Metode HTTP API, seperti: GET, PUT, POST, atau HAPUS.
  • 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 mengupdate node Drupal yang ada.

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

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

Untuk mengekspor model:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang ingin Anda ekspor, pilih Ekspor di bagian Operasi.
  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 admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen 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 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 transformer. Perhatikan bahwa impor akan membuat revisi baru dari model.
  8. Merender dan memublikasikan node.

Mengedit template SmartDocs

Template SmartDocs menentukan tampilan node Drupal Anda di layar. Setiap SmartDocs model ini dapat menggunakan template default yang sama atau Anda dapat menyesuaikan template secara manual untuk model individu.

Template SmartDocs mencakup file template yang dikodekan sebagai file .hbr Handlebars, file CSS, dan JavaScript. Dengan Handlebar, banyak konten yang digerakkan oleh variabel menggunakan sematan ekspresi handlebars, seperti &123;&123;body}}. Daftar yang ada Ekspresi handlebar disediakan dalam komentar di bagian atas file. Untuk mengetahui informasi tentang menggunakan Handlebar untuk menyesuaikan template, lihat http://handlebarsjs.com.

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

Mengupload kustom File template SmartDocs

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 dalam model yang ada.

Jika Anda 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 dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konfigurasi > SmartDocs di Drupal menu administrasi.
  3. Luaskan area Setelan Lanjutan di halaman.
  4. Di bagian Upload {i>custom method template<i}, klik Choose File, dan arahkan ke file .hbr Handlebars.
  5. Klik Upload.
  6. Klik Simpan konfigurasi.

Memulihkan file template SmartDocs default

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

Untuk memulihkan file template SmartDocs default:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konfigurasi > SmartDocs di Drupal menu administrasi.
  3. Luaskan area Setelan Lanjutan di halaman.
  4. Di bawah Upload template metode yang disesuaikan, klik Remove di samping file template SmartDocs kustom.
  5. Klik Simpan konfigurasi.

Memodifikasi template SmartDocs untuk setiap model

Anda dapat mengubah template yang digunakan untuk setiap model.

Untuk mengubah template model perorangan:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang ingin Anda edit, pilih Setelan di bagian Operasi.
  4. Di area Method Template, edit template sesuai kebutuhan.
  5. Klik Save template.
  6. Cari node Drupal. Anda akan melihat perubahan template di halaman.

Mengonfigurasi Jenis autentikasi SmartDocs

API yang ditentukan di SmartDocs dapat terbuka, artinya tidak ada kredensial autentikasi yang yang diperlukan untuk mengaksesnya, atau mengamankan. API yang aman mengharuskan Anda meneruskan kredensial saat melakukan ke API.

Untuk API yang aman, SmartDocs mendukung jenis autentikasi berikut:

  • Autentikasi dasar - Teruskan kredensial autentikasi dasar sebagai pasangan nama pengguna dan {i>password<i}. Jika Anda tidak menentukan untuk menggunakan OAuth sebagai jenis kredensial, API secara {i>default<i} untuk menggunakan otentikasi dasar.
  • OAuth 2.0 - Penyedia layanan pihak ketiga mengautentikasi kredensial pengguna kredensial, memastikan bahwa pengguna memiliki otorisasi ke API, dan kemudian mengeluarkan sebelumnya yang benar. Saat Anda membuat permintaan SmartDocs ke API yang dilindungi, SmartDocs akan membuat permintaan dan mengirimkannya ke penyedia layanan. Penyedia layanan kemudian memvalidasi token dan memastikan bahwa masa berlakunya belum berakhir.
  • Token kustom - Meneruskan nilai token sebagai header atau parameter kueri ke setiap nilai token permintaan.

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

Skema keamanan dikaitkan dengan revisi suatu model secara spesifik. Oleh karena itu, jika Anda membuat revisi model yang baru, Anda harus mendefinisikan ulang skema keamanan untuk revisi itu

Dalam file WADL, Anda menentukan apakah API memerlukan autentikasi atau tidak menggunakan tag Apigee &lt;apigee:authentication&gt;, sebagai yang ditampilkan 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 dalam file WADL. Anda melakukannya dengan mengedit node di Drupal. Untuk informasi selengkapnya tentang file WADL, lihat WADL Referensi.

Pada halaman API di Drupal, SmartDocs menambahkan tombol berikut untuk memungkinkan pengguna menentukan kredensial otentikasi 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 menentukan tag &lt;apigee:authentication&gt; di 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 admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang diinginkan, pilih Revisi API di bagian Operasional.
  4. Untuk revisi model yang ingin Anda edit, pilih Keamanan Setelan 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 skema dasar Anda.
    1. Pilih Konten > SmartDokumen di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih Revisi API di bagian Operasional.
    3. Untuk revisi model yang ingin Anda edit, pilih Revisi Detail di bagian Operasi.
    4. Pilih Edit Method untuk API yang ingin diedit.
    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 setelan default autentikasi. Anda mengonfigurasi OAuth di dua lokasi:

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

Untuk mengaktifkan OAuth:

  1. Login ke portal Anda sebagai pengguna dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen 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 Authorization URL. Otorisasi URL digunakan untuk memperoleh token akses.
  10. Tetapkan Verb Otorisasi 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 Token Akses.
  13. Gunakan In untuk menentukan cara meneruskan token: Header, Kueri, atau Isi.
  14. Tetapkan Cakupan OAuth.
  15. Pilih Kirim.
  16. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  17. Untuk model, pilih Settings di Operations drop-down.
  18. Masukkan nilai di ID Klien dan Klien Rahasia.
  19. Pilih Save template authentication settings.
  20. Untuk setiap metode dalam model, edit metode tersebut untuk menetapkan Skema Keamanan skema keamanan OAuth Anda.
    1. Pilih Konten > SmartDokumen di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih Revisi API di bagian Operasional.
    3. Untuk revisi model yang ingin Anda edit, pilih Revisi Detail di bagian Operasi.
    4. Pilih Edit Method untuk API yang ingin diedit.
    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 dengan hak istimewa admin atau pembuatan konten.
  2. Pilih Konten > SmartDokumen di menu administrasi Drupal.
  3. Untuk model yang diinginkan, pilih Revisi API di bagian Operasional.
  4. Untuk revisi model yang ingin Anda edit, pilih Keamanan Setelan di bagian Operasi.
  5. Pilih Add Security Scheme.
  6. Tentukan name 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 > SmartDokumen di menu administrasi Drupal.
    2. Untuk model yang diinginkan, pilih Revisi API di bagian Operasional.
    3. Untuk revisi model yang ingin Anda edit, pilih Revisi Detail di bagian Operasi.
    4. Pilih Edit Method untuk API yang ingin diedit.
    5. Pilih Security Scheme untuk API.
    6. Simpan API.

Menghapus model

Saat Anda menghapus model (Konten > SmartDocs, Hapus di kolom Operations di Drupal), model 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.