Dokumentasi API profesional layak menggunakan domain profesional. Secara default, dokumentasi Apidog dapat diakses pada domain <subdomain>.apidog.io. Namun, Anda dapat menyesuaikannya dengan menyiapkan domain Anda sendiri, sehingga audiens Anda dapat mengakses dokumentasi pada domain yang selaras dengan branding organisasi Anda.
Untuk mengakses pengaturan domain kustom, buka menu Publish Docs di sidebar, lalu masuk ke halaman pengaturan Publish. Anda akan menemukan bagian Custom Domain tempat Anda dapat mengeklik tombol Edit untuk memulai penyiapan.
Terdapat dua jenis opsi untuk mengatur domain kustom:
1.
CNAME (Direkomendasikan): Paling mudah untuk disiapkan dan dipelihara; berfungsi untuk subdomain maupun domain root, sehingga memberikan fleksibilitas maksimum.
2.
Reverse Proxy (Lanjutan): Memerlukan penggunaan Content Delivery Network (CDN) atau penyiapan reverse proxy di server Anda sendiri; direkomendasikan untuk pengguna yang memahami teknologi ini.
Nama field dan langkah konfigurasi dapat berbeda antar panel kontrol DNS, tetapi konsep intinya tetap sama. Jika Anda tidak yakin, verifikasikan dengan penyedia DNS Anda.
type adalah jenis record DNS yang ingin Anda buat. Di sini, Anda perlu memilih CNAME.
name atau DNS entry adalah tempat Anda memasukkan subdomain Anda. Anda mungkin perlu memasukkannya secara lengkap (misalnya docs.example.com) atau cukup memasukkan bagian sebelum domain apex Anda (misalnya docs). Jika Anda tidak yakin mana yang harus digunakan, tanyakan kepada penyedia DNS Anda.
target atau value atau destination adalah tujuan subdomain tersebut diarahkan. Anda dapat melihat nilai ini di pengaturan Publish di Apidog saat memilih opsi DNS CNAME. Bentuknya akan terlihat seperti {docsSiteId}.apidog.io. Anda harus memasukkan nilai ini secara lengkap (misalnya 12345678.apidog.io).
Anda juga mungkin melihat field bernama TTL, yang merupakan singkatan dari Time To Live. Ini adalah jumlah detik record DNS dapat di-cache. Jika Anda tidak yakin nilai yang harus diatur, kami menyarankan untuk memilih Auto atau tetap menggunakan nilai default.
Berikut adalah contoh tampilan konfigurasi yang benar di panel kontrol Cloudflare:
Record CNAME tidak dapat berdampingan dengan record lain untuk nama yang sama. Jika Anda sudah memiliki record A, record AAAA, record TXT, atau jenis record lainnya untuk subdomain yang Anda pilih, Anda perlu menghapusnya terlebih dahulu, sebelum menambahkan record CNAME.
Apakah Anda menggunakan Cloudflare?
Jika Anda mengonfigurasi DNS di panel kontrol Cloudflare, pastikan proxying Cloudflare (awan oranye, juga disebut "Proxy status" di pengaturan domain Anda) dinonaktifkan. Hal ini dilakukan karena dua alasan:
Opsi ini menyamarkan target DNS untuk domain Anda dari publik, sehingga mencegah Apidog menjalankan pemeriksaan rutin dengan benar pada domain kustom Anda.
Domain kustom Anda sudah akan mendapatkan manfaat dari CDN.
Sekali lagi, harap nonaktifkan Cloudflare proxying untuk memastikan dokumentasi Anda disajikan tanpa masalah.
Berapa Lama Waktu yang Dibutuhkan agar Perubahan Mulai Berlaku?#
Jawaban singkatnya: Anda mungkin perlu menunggu 10 menit hingga 48 jam agar perubahan DNS mulai berlaku sebelum melanjutkan ke langkah berikutnya.Ingat field TTL (Time To Live) yang disebutkan sebelumnya? Record DNS di-cache selama jangka waktu tertentu — yang biasanya sangat baik untuk alasan performa, karena record tersebut umumnya tidak sering berubah. Ketika record tersebut berubah, terdapat periode waktu (nilai TTL) ketika server cache DNS perlu menunggu cache-nya kedaluwarsa sebelum memeriksa perubahan dan bertindak sesuai hasilnya.Dalam kebanyakan kasus, sebaiknya tunggu setidaknya 10 menit sebelum melanjutkan ke langkah berikutnya dan terakhir. Terkadang semuanya dapat diperbarui sedikit lebih cepat, atau dapat memakan waktu lebih lama. Jarang sekali proses ini memakan waktu lebih dari 48 jam.Ingin memeriksa bagaimana proses ini, yang dikenal sebagai propagation, berjalan? Anda dapat menggunakan alat DNS lookup, seperti WhatsMyDNS. Masukkan subdomain lengkap Anda, pilih CNAME dari daftar dropdown, lalu tekan tombol Search. Server cache DNS di seluruh dunia akan merespons untuk memberi tahu Anda hasil cache mereka. Anda perlu memeriksa hasil ini secara berkala hingga sebagian besar merespons dengan nilai CNAME yang ditetapkan untuk Anda.
Mengonfigurasi CDN atau Server Reverse Proxy Anda Sendiri#
Penerapan
Bagian ini hanya berlaku jika Anda memilih opsi Reverse Proxy pada langkah sebelumnya.
Anda dapat memanfaatkan layanan CDN yang disediakan oleh vendor cloud seperti AWS CloudFront, Cloudflare Enterprise untuk menyiapkannya sebagai server reverse proxy Anda sendiri.Dalam contoh berikut, kami akan mengonfigurasi AWS CloudFront sebagai Reverse Proxy.
1.
Masuk ke AWS, lalu buka CloudFront. Klik Create Distribution.
2.
Konfigurasikan pengaturan distribution Anda. Berikut adalah nilai yang perlu Anda ubah.
Pengaturan
Nilai
Origin Domain Name
Atur ke {docsSiteId}.apidog.io
Name
Deskripsi untuk origin. Nilai ini memungkinkan Anda membedakan beberapa origin dalam distribution yang sama, sehingga harus unik.
Origin Protocol Policy
Atur ke HTTP Only
Alternate Domain Names (CNAMEs)
Atur ke nama domain kustom Anda (domain yang sama dengan yang Anda konfigurasi di pengaturan Publish saat penyiapan domain kustom)
SSL Certificate
Atur ke SSL Certificate untuk domain kustom Anda yang disimpan di AWS Certificate Manager (ACM).
3.
Berikan informasi pada Origin Custom Headers (field Header Name dan Value hanya muncul setelah Anda memberikan Origin Domain Name)
Header Name
Nilai
X-Apidog-Docs-Site-ID
Atur ke {docsSiteId}
{docsSiteId} adalah Docs Site ID Anda, yang dapat ditemukan di panel domain kustom. Pastikan Anda memasukkan ID yang benar.
4.
Konfigurasikan Default Cache Behavior Settings. Berikut adalah nilai yang perlu Anda ubah.
Pengaturan
Nilai
Viewer Protocol Policy
Pilih Redirect HTTP to HTTPS
Allowed HTTP Methods
Pilih GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
Cache and origin request settings
Pilih Use legacy cache settings. Pilih All untuk Headers, Query strings, dan Cookies
5.
Jangan aktifkan AWS Web Application Firewall (WAF).
6.
Klik Create distribution di bagian bawah halaman. Anda akan melihat distribution yang baru dibuat dalam daftar CloudFront Distributions Anda. Perhatikan bahwa Status akan menampilkan In progress hingga distribution berstatus Deployed.
7.
Tambahkan record CNAME baru ke DNS Anda untuk domain kustom Anda yang mengarah ke CloudFront Domain Name untuk Distribution Anda. Ini dapat ditemukan dengan mengeklik Distribution ID Anda, pada tab General, Distribution domain name (misalnya, fd1fbc7cac6197.cloudfront.net).
Anda dapat menggunakan Cloudflare Workers untuk bertindak sebagai reverse proxy. Ini memungkinkan Anda mempertahankan domain Anda tetap diproxy (Orange Cloud) sekaligus memastikan Apidog menerima pengidentifikasi proyek yang diperlukan.
Klik Create Application, lalu Create Worker. (Lanjutkan dengan Start with Hello World!, jika diminta untuk memilih metode)
3.
Beri nama worker Anda (misalnya, apidog-docs-proxy) dan klik Deploy.
4.
Klik Edit Code dan ganti skrip yang ada dengan berikut ini:
Anda dapat menemukan {docsSiteId} di panel domain kustom. Pastikan Anda memasukkan ID yang benar pada variabel targetHost dan docsSiteId.
5.
Klik Save and Deploy.
6.
Buka tab Settings pada Worker Anda, pilih Domains & Routes, lalu klik tombol +Add.
7.
Masukkan domain kustom Anda (misalnya, docs.example.com). Cloudflare akan secara otomatis menangani record DNS dan sertifikat SSL.
8.
Pastikan SSL/TLS encryption mode Cloudflare Anda diatur ke Full atau Full (Strict) untuk memungkinkan komunikasi yang aman antara Cloudflare dan Apidog.
Prasyarat
Sebelum melampirkan domain kustom ke worker Anda, pastikan domain tersebut (misalnya, example.com) sudah ditambahkan ke akun Cloudflare Anda dan nameserver-nya aktif.
Anda dapat mengonfigurasi server reverse proxy Anda sendiri untuk dokumentasi API Anda. Dalam contoh berikut, kami akan menggunakan Nginx sebagai server reverse proxy.
1.
Tambahkan konten berikut ke file konfigurasi Nginx untuk konfigurasi sederhana.
{docsSiteId} adalah Docs Site ID Anda, yang dapat ditemukan di panel domain kustom. Pastikan Anda memasukkan ID yang benar.
2.
Konfigurasikan record DNS untuk nama domain kustom Anda agar mengarah ke server reverse proxy Anda.
Men-deploy Dokumen API ke Subdirektori Domain Kustom#
Reverse Proxy Apidog memungkinkan dokumen API di-deploy ke subdirektori dari domain kustom. Misalnya, Anda dapat men-deploy dokumentasi ke path /api-docs pada domain seperti https://example.com. Saat pengguna mengunjungi https://example.com/api-docs, mereka akan mengakses dokumentasi API online yang di-host oleh Apidog.
Pada halaman pengaturan Custom Domain Apidog, masukkan domain kustom Anda.
2.
Pilih Reverse Proxy dan aktifkan Use Subdirectory, lalu masukkan path subdirektori.
3.
Berikutnya, Anda perlu memodifikasi file konfigurasi server web Anda. Dengan asumsi Anda menggunakan Nginx untuk mem-proxy layanan Anda, Anda dapat merujuk pada konfigurasi berikut:
proxy_pass: Meneruskan permintaan klien ke server lain (seperti server dokumentasi API Apidog).
proxy_set_header: Mengatur header permintaan yang dikirim oleh server proxy ke server upstream, memastikan permintaan ditangani dengan benar.
/api-docs/ adalah subdirektori domain kustom, dan harus diakhiri dengan / dalam konfigurasi Nginx.
http://{docsSiteId}.apidog.io/ juga harus diakhiri dengan /.
Ganti {docsSiteId} dengan ID situs dokumen Apidog Anda.
docs.example.com adalah contoh domain kustom. Ganti dengan domain kustom Anda yang sebenarnya.
Setelah konfigurasi, Anda perlu memulai ulang Nginx di server Anda.
Dokumentasi online Apidog mendukung protokol HTTPS, yang memiliki beberapa keunggulan dibandingkan HTTP:
Transmisi data yang aman: HTTPS menggunakan enkripsi SSL/TLS untuk memastikan keamanan transmisi data, sehingga mencegah pihak ketiga menyadap informasi.
Optimisasi SEO: Crawler mesin pencari lebih memilih menggunakan HTTPS karena menawarkan keamanan dan perlindungan privasi yang lebih baik. Oleh karena itu, situs web HTTPS dapat memiliki otoritas yang lebih tinggi dalam peringkat mesin pencari dibandingkan situs web HTTP.
Aktifkan HTTPS untuk mengaktifkan HTTPS, dan secara opsional, Anda dapat mengaktifkan Always Use HTTPS untuk mencegah komunikasi dibajak atau terkena serangan man-in-the-middle.
Jika Anda menggunakan Apidog Europe, pastikan Anda menggunakan domain yang benar untuk penyiapan domain kustom Anda.Domain yang benar untuk Apidog Europe dalam penyiapan sebelumnya adalah {docsSiteId}.eu.apidog.com.
