Keamanan Dokumentasi API: Apakah Spesifikasi Anda Aman di Git?

Keamanan dokumentasi API adalah bagian dari program API Anda yang hampir tidak pernah diaudit. Anda memperkuat API itu sendiri dengan otentikasi, pembatasan laju, dan pengujian keamanan. Namun, dokumentasi yang menjelaskan API tersebut, spesifikasi OpenAPI, halaman Swagger UI, markah yang menjelaskan alur otentikasi Anda, seringkali tersimpan di repositori Git atau pada host statis yang belum pernah ditinjau siapa pun sejak pertama kali diatur. Pada 20 Mei 2026, GitHub mengonfirmasi bahwa penyerang mencuri data dari sekitar 3.800 repositori kode internalnya. Titik masuknya adalah ekstensi VS Code yang terinfeksi yang diinstal pada laptop karyawan GitHub. Pelanggaran tersebut adalah alasan bagus untuk mengajukan pertanyaan tidak nyaman tentang pengaturan Anda sendiri: jika seseorang dapat secara diam-diam mengubah dokumentasi API Anda yang telah diterbitkan, apakah Anda akan menyadarinya, dan apakah konsumen API Anda akan menyadarinya?

TL;DR

Dokumentasi API yang aman berarti dokumen Anda memiliki kontrol akses, riwayat versi, integritas yang dapat Anda verifikasi, dan jejak audit, sehingga repositori atau host yang disusupi tidak dapat secara diam-diam menyalurkan titik akhir, token, atau instruksi otentikasi yang salah kepada pengembang yang menyalinnya ke dalam produksi. Dokumentasi sebagai kode (docs-as-code) di Git baik-baik saja untuk banyak tim dan memberi Anda tinjauan serta riwayat secara gratis. Ini menjadi kerugian ketika repositori bersifat publik tanpa kontrol akses, ketika spesifikasi usang menyimpang dari API langsung, atau ketika contoh yang dimanipulasi mencapai konsumen tanpa terdeteksi. Lapisan dokumentasi terkelola seperti Apidog menambahkan perlindungan kata sandi, daftar izin IP dan email, domain kustom, versi, dan spesifikasi yang tetap sinkron dengan desain API Anda sebagai sumber kebenaran.

Mengapa pelanggaran GitHub harus membuat Anda melihat dokumentasi API Anda

Insiden GitHub layak dipahami sebelum Anda panik. Kelompok ancaman TeamPCP mengeksfiltrasi repositori internal GitHub dan sekarang menjual set data tersebut dengan harga lebih dari $50.000 di forum bawah tanah. Liputan BleepingComputer mengonfirmasi bahwa ekstensi VS Code berbahaya tersebut berasal langsung dari pasar resmi dan berjalan di perangkat karyawan. GitHub mengatakan tidak menemukan bukti bahwa data pelanggan yang disimpan di luar repositori internalnya terpengaruh, dan investigasi sedang berlangsung.

Yang dilakukan pelanggaran ini adalah memberi Anda sebuah pengingat. Ini adalah pengingat untuk melihat di mana dan bagaimana dokumentasi API Anda berada, dan apakah itu dapat dirusak. Sebagian besar tim tidak pernah menanyakan hal itu. Mereka menerbitkan Swagger UI ke GitHub Pages tiga tahun lalu, mengarahkan CNAME ke sana, dan melanjutkan. Repositori bersifat publik. Spesifikasi adalah apa pun yang terakhir digabungkan. Tidak ada yang meninjau perubahan pada situs dokumen dengan kehati-hatian yang sama seperti yang mereka terapkan pada kode aplikasi.

Kesenjangan itu penting karena dokumentasi API adalah instruksi. Ketika seorang pengembang mengintegrasikan dengan API Anda, mereka menyalin jalur titik akhir, bentuk permintaan, header otentikasi, dan seringkali nilai contoh langsung dari dokumentasi Anda ke dalam kode mereka. Jika penyerang dapat mengubah instruksi tersebut, mereka tidak merusak halaman pemasaran. Mereka sedang mengedit kode yang akan dijalankan orang lain. Logika yang sama muncul dalam tinjauan pasca-insiden pelanggaran lain tahun 2026; tulisan kami tentang pelajaran keamanan API dari pelanggaran Vercel mencakup bagaimana perubahan kecil pada permukaan yang dipercaya menyebar ke luar.

Artikel ini membahas empat hal: cara konkret dokumentasi API yang disusupi merugikan konsumen Anda, kapan docs-as-code-in-Git benar-benar baik versus kapan menjadi kerugian, apa sebenarnya arti "dokumentasi API yang aman" sebagai daftar periksa, dan bagaimana lapisan dokumentasi terkelola menutup celah tersebut. Dua artikel terkait lainnya membahas lebih dalam tentang sudut pandang terkait: apa arti pelanggaran GitHub bagi alat API yang di-host sendiri dan keamanan kunci API ekstensi VS Code.

Apa yang salah ketika repositori atau host dokumen API Anda disusupi

Mulailah dengan model ancaman. Dokumen API Anda berada di suatu permukaan: repositori Git, pipeline CI yang membangunnya, dan host yang menyajikannya. Menyusupi salah satu di antaranya akan diikuti oleh beberapa hasil buruk tertentu. Tidak ada di antaranya yang bersifat teoretis.

Perusakan dokumentasi mencapai kode produksi

Ini adalah kasus terburuk dan yang paling tidak jelas. Penyerang dengan akses tulis ke repositori dokumen Anda, atau ke host yang menyajikan situs yang dibangun, membuat sedikit perubahan. Mereka mengubah https://api.payments.acme.com/v2/charge menjadi domain yang mereka kendalikan. Mereka menukar token pembawa contoh di halaman "Memulai" Anda dengan token yang mengarahkan melalui proksi mereka. Mereka menulis ulang satu kalimat di bagian OAuth Anda sehingga pertukaran token memposting ke URL yang salah.

Tidak ada satu pun yang merusak situs Anda. Halaman tetap dirender. CI masih lolos, karena spesifikasi masih YAML yang valid. Tetapi pengembang berikutnya yang mengintegrasikan dengan API Anda menyalin titik akhir atau alur tersebut ke dalam layanan mereka. Perubahan tersebut sekarang berjalan di lingkungan produksi mereka, dan mereka mempercayainya karena berasal dari dokumen resmi Anda.

Pertimbangkan fragmen OpenAPI yang realistis. Sebuah tim mendokumentasikan titik akhir pembayaran seperti ini:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Satu perubahan pada URL servers itu, digabungkan melalui akun yang disusupi atau didorong ke host yang dibajak, dan setiap konsumen yang meregenerasi klien dari spesifikasi kini mengirimkan data kartu ke domain penyerang. Perbedaan hanyalah dua kata. Tidak ada yang menandai dua kata dalam komit dokumen.

Titik akhir internal dan tidak terdokumentasi bocor

Repositori dokumen mengakumulasi banyak hal. Spesifikasi yang dimulai sebagai API publik seringkali tumbuh menjadi jalur internal saja, titik akhir admin, rute debug, atau operasi khusus mitra yang tidak pernah dimaksudkan untuk dipublikasikan. Jika repositori bersifat publik, atau menjadi publik karena kesalahan konfigurasi, titik akhir tersebut kini menjadi peta bagi siapa pun yang memindai permukaan serangan Anda.

Bahkan repositori pribadi pun menjadi masalah di sini. Pelanggaran seperti GitHub mengeksfiltrasi repositori pribadi. Saat spesifikasi API internal Anda berada dalam repositori yang dicuri, penyerang memiliki inventaris yang tepat dari titik akhir, parameter, dan muatan yang diharapkan. Mereka tidak perlu menebak. Anda telah menyerahkan skema tersebut kepada mereka. Jika Anda menginginkan kerangka kerja untuk menemukan celah-celah ini sebelum orang lain melakukannya, daftar periksa pengujian keamanan API kami untuk tahun 2026 dibangun berdasarkan jenis tinjauan permukaan ini.

GitHub Pages Publik tidak memiliki kontrol akses

GitHub Pages adalah host statis. Ini menyajikan berkas. Ini tidak memiliki konsep siapa yang membacanya. Untuk API yang benar-benar publik, itu benar dan baik-baik saja. Untuk dokumen yang seharusnya hanya terlihat oleh pelanggan berbayar, kepada sekumpulan mitra tertentu, atau kepada tim Anda sendiri, itu adalah alat yang salah, karena sama sekali tidak ada gerbang.

Tim mengatasi ini dengan "keamanan melalui URL yang sulit ditebak." Dokumen berada di jalur yang tidak dihubungkan oleh siapa pun. Itu bukan kontrol akses. URL bocor melalui riwayat browser, header perujuk, log proxy, dan bookmark bersama. Siapa pun yang menemukan tautan melihat semuanya, selamanya, tanpa cara bagi Anda untuk mengetahui bahwa mereka melakukannya.

Dokumen usang dan tidak dapat diverifikasi

Mode kegagalan yang lebih senyap sama sekali tidak memerlukan penyerang. Dokumen dalam repositori Git menyimpang. Seseorang mengirimkan perubahan API, lupa memperbarui spesifikasi, dan markah sekarang menjelaskan titik akhir yang berperilaku berbeda dalam produksi. Konsumen mengintegrasikan terhadap perilaku yang didokumentasikan, menemukan perilaku sebenarnya, dan menghabiskan sehari untuk melakukan debug.

Ketika dokumen disusupi, masalah ini menjadi lebih buruk, karena Anda kehilangan kemampuan untuk membedakan penyimpangan dari perusakan. Apakah titik akhir itu selalu salah, atau seseorang mengubahnya? Tanpa riwayat yang dapat diverifikasi yang terikat dengan desain API Anda yang sebenarnya, Anda tidak dapat menjawabnya. Dokumen menjadi tidak dapat diverifikasi, dan dokumen yang tidak dapat diverifikasi tidak jauh lebih baik daripada tidak ada dokumen.

Kapan docs-as-code di Git baik-baik saja, dan kapan menjadi kerugian

Docs-as-code adalah praktik yang sah dan populer, dan bagian ini bukanlah argumen menentangnya. Menempatkan spesifikasi OpenAPI dan markah Anda di repositori Git, membangun Swagger UI atau Redoc dengan CI, dan menerapkan ke host statis memberi Anda manfaat nyata. Anda mendapatkan tinjauan permintaan tarik pada perubahan dokumentasi. Anda mendapatkan riwayat lengkap tentang siapa yang mengubah apa dan kapan. Anda mendapatkan versi dokumen bersama dengan kode. Itu adalah properti persis yang membuat perusakan dapat dideteksi, ketika alur kerja diikuti.

Jadi pertanyaannya bukan “Git atau bukan Git.” Ini adalah “apakah pengaturan khusus ini aman untuk API khusus ini.” Berikut adalah bagaimana kedua kasus ini terbagi.

Docs-as-code di Git baik-baik saja ketika

Praktik ini bekerja dengan baik di bawah serangkaian kondisi tertentu:

• API bersifat sepenuhnya publik, jadi tidak ada yang disembunyikan dan tidak memerlukan kontrol akses.
• Repositori memiliki perlindungan cabang, tinjauan yang diperlukan, dan sekumpulan kecil orang yang diaudit dengan akses tulis.
• Perubahan dokumen melewati ketelitian tinjauan yang sama dengan kode, sehingga URL atau token yang tertukar akan terdeteksi dalam tinjauan.
• Pipeline build terkunci: tindakan yang dipatok, tidak ada langkah pihak ketiga yang tidak ditinjau, kredensial penyebaran yang dibatasi.
• Spesifikasi dihasilkan dari atau divalidasi terhadap API nyata, bukan diedit secara manual dan diharapkan.
• Seseorang bertanggung jawab untuk menjaga spesifikasi tetap terkini, sehingga penyimpangan tidak terakumulasi.

Jika semua itu berlaku, dokumen yang di-host di Git adalah sistem yang kuat dan transparan. Riwayat adalah jejak audit Anda. Tinjauan adalah pemeriksaan integritas Anda.

Docs-as-code di Git menjadi kerugian ketika

Pengaturan yang sama menjadi berisiko ketika kondisi meleset:

• Dokumen seharusnya bersifat pribadi atau hanya untuk mitra, tetapi host tidak memiliki kontrol akses, sehingga "pribadi" berarti "tidak tertaut."
• Akses tulis bersifat luas, atau mencakup akun layanan dan token CI yang tidak dilacak oleh siapa pun.
• Komit dokumen diabaikan, karena "hanya dokumen," sehingga perbedaan berbahaya lolos begitu saja.
• Spesifikasi dikelola secara manual dan menyimpang dari API langsung, sehingga konsumen tidak dapat mempercayainya.
• Repositori menyimpan titik akhir internal atau tidak terdokumentasi bersama dengan yang publik.
• Tidak ada sinyal integritas: tidak ada yang bisa memberi tahu Anda apakah situs yang diterapkan cocok dengan sumber yang ditinjau.

Pelanggaran GitHub secara langsung mengenai mode kegagalan ini. Serangan datang melalui titik akhir pengembang dan mencapai repositori internal. Jika spesifikasi API pribadi Anda berada di salah satu repositori tersebut, pelanggaran tersebut mengungkap skema Anda terlepas dari seberapa hati-hati proses tinjauan Anda. Git memberi Anda transparansi; itu tidak memberi Anda kerahasiaan setelah repositori itu sendiri dicuri. Untuk perbandingan lebih lengkap tentang posisi berbagai pendekatan dokumentasi yang di-host sendiri terhadap pertukaran ini, lihat perbandingan dokumen API yang di-host sendiri kami.

Poin utamanya sengaja diseimbangkan. Pertahankan docs-as-code jika API Anda publik dan pipeline Anda disiplin. Pertimbangkan kembali jika dokumen Anda memerlukan kontrol akses, jika proses tinjauan Anda memperlakukan dokumen sebagai kelas dua, atau jika Anda tidak dapat menjawab “apakah situs langsung cocok dengan sumber yang ditinjau.”

Apa sebenarnya arti “dokumentasi API yang aman”

“Dokumentasi API yang aman” menjadi samar sampai Anda memecahnya menjadi properti yang dapat Anda periksa. Empat di antaranya memegang peran penting.

Kontrol akses

Dokumen hanya terlihat oleh orang-orang yang seharusnya melihatnya. Publik untuk API publik. Dibatasi untuk dokumen khusus pelanggan, khusus mitra, atau internal. Pembatasan harus berupa gerbang nyata, kata sandi, daftar izin IP, daftar izin email, atau SSO, bukan URL yang samar. Uji coba: bisakah Anda menyebutkan dengan tepat siapa yang dapat membaca dokumen Anda saat ini, dan mencabut akses salah satu dari mereka dalam waktu kurang dari satu menit?

Versioning

Setiap versi dokumen yang diterbitkan diawetkan dan dapat diidentifikasi. Konsumen API v1 Anda melihat dokumen v1; konsumen v2 melihat v2. Anda dapat menunjukkan apa yang dikatakan dokumen pada tanggal tertentu. Uji coba: bisakah pengembang yang berintegrasi dengan versi API Anda yang lebih lama masih menemukan dokumen yang akurat untuk itu, alih-alih dokumen yang secara diam-diam diperbarui ke v2?

Integritas

Anda dapat memverifikasi bahwa dokumen yang diterbitkan cocok dengan yang Anda maksudkan. Dokumen tersebut dapat dihasilkan dari sumber kebenaran yang terkontrol, atau ada jejak tinjauan dan riwayat yang cukup kuat sehingga perubahan yang tidak sah menonjol. Uji coba: jika seseorang mengubah satu URL titik akhir pada dokumen langsung Anda satu jam yang lalu, apakah ada sesuatu yang akan memberi tahu Anda?

Jejak audit

Anda dapat menjawab siapa yang mengubah dokumen, apa yang mereka ubah, dan kapan. Riwayat Git memberi Anda ini untuk repositori; Anda juga membutuhkannya untuk permukaan yang diterbitkan, karena langkah penyebaran adalah titik serangannya sendiri. Uji coba: bisakah Anda menghasilkan log perubahan untuk dokumen Anda yang diterbitkan selama 90 hari terakhir?

Pengaturan yang memenuhi keempatnya adalah dokumentasi yang aman. Dokumen yang di-host di Git dapat mencapai versioning, integritas, dan jejak audit melalui perlindungan cabang dan riwayat. Yang biasanya mereka lewatkan pada host statis adalah kontrol akses, dan celah itulah yang menjadi alasan untuk lapisan dokumentasi terkelola.

Bagaimana Apidog Memberikan Anda Dokumentasi API yang Aman

Apidog adalah platform API lengkap untuk mendesain, men-debug, menguji, melakukan mocking, dan mendokumentasikan API. Sisi dokumentasi dibangun agar empat properti di atas menjadi standar daripada hal-hal yang Anda tambahkan. Untuk mengikutinya, unduh Apidog dan buka proyek apa pun dengan definisi API.

Dokumentasi yang Diterbitkan dari Sumber Kebenaran yang Terkendali

Di Apidog, dokumentasi dihasilkan dari desain API Anda di dalam proyek. Anda mendesain titik akhir, skema, dan otentikasi di desainer visual, dan Apidog secara otomatis menghasilkan dokumentasi dari definisi tersebut. Klik Publikasikan dan Anda akan mendapatkan situs dokumen interaktif dengan konsol "Coba" dan contoh kode multibahasa.

Manfaat integritas bersifat struktural. Dokumen yang diterbitkan bukanlah markah yang dapat diedit secara terpisah yang dapat menyimpang atau dirusak dengan sendirinya. Dokumen tersebut mencerminkan definisi API. Ubah definisi, dokumen akan mengikuti. Untuk mengubah apa yang dilihat konsumen, Anda mengubah desain di dalam proyek, yang memiliki izin dan riwayat perubahan sendiri, alih-alih mengedit berkas yang tidak terikat pada host statis.

Kontrol Akses Dokumentasi

Di sinilah Apidog menutup celah GitHub Pages. Saat Anda memublikasikan, Anda memilih visibilitas, dan pilihannya adalah gerbang nyata, bukan ketidakjelasan:

• Publik: siapa pun dengan tautan dapat membacanya. Tepat untuk API yang benar-benar terbuka.
• Perlindungan kata sandi: atur kata sandi (atau buat yang acak) dan bagikan dengan pemangku kepentingan. Hanya orang dengan kata sandi yang dapat masuk.
• Daftar izin IP: batasi akses ke IP atau rentang tertentu, seperti kantor atau VPN Anda. Berguna untuk dokumen internal.
• Daftar izin email: cantumkan alamat email atau domain yang diizinkan; pengguna memverifikasi dengan kode sekali pakai. Wildcard seperti *@yourcompany.com mencakup seluruh organisasi.
• Login kustom: hubungkan sistem otentikasi Anda sendiri; server Anda mengeluarkan JWT, Apidog memverifikasinya, dan akses tergantung pada validitas.

Apidog mendokumentasikan kelima metode dalam panduan untuk mengontrol akses dokumentasi API-nya. Itu menjawab uji kontrol akses secara langsung: Anda dapat menyatakan siapa yang dapat membaca dokumen, dan Anda dapat mencabut kata sandi atau menghapus email dari daftar izin segera.

Domain Kustom

Anda dapat menyajikan dokumen yang diterbitkan di domain Anda sendiri, sehingga konsumen melihat developer.yourcompany.com alih-alih URL umum. Apidog mendukung domain kustom melalui CNAME DNS (jalur yang direkomendasikan) atau proxy terbalik. Domain kustom saja bukanlah kontrol keamanan, tetapi itu menjaga dokumen Anda pada infrastruktur yang Anda kelola dan atur, daripada tersebar di host yang tidak dimiliki siapa pun.

Spesifikasi OpenAPI tetap sinkron dengan desain API Anda

Penyimpangan adalah masalah keamanan dokumentasi karena membuat dokumen tidak dapat diverifikasi. Apidog memperlakukan desain API sebagai satu-satunya sumber kebenaran dan menjaga dokumentasi tetap sinkron saat desain berubah. Apidog mengimpor OpenAPI 3.0, 3.1, dan Swagger 2.0, serta mendukung impor terjadwal sehingga spesifikasi eksternal tetap terkini secara otomatis.

Jika Anda saat ini memelihara spesifikasi secara manual di repositori Git, itu adalah pengaturan dengan penyimpangan tertinggi dan tersulit untuk diverifikasi. Memindahkan spesifikasi ke Apidog sebagai sumber kebenaran berarti dokumen yang diterbitkan selalu cocok dengan definisi yang Anda kontrol. Tim yang beralih dari SwaggerHub dapat mengikuti panduan kami untuk memigrasi dokumen API SwaggerHub ke Apidog.

Versioning Dokumentasi

Apidog mendukung versioning dokumentasi, sehingga Anda dapat memublikasikan dan menyimpan beberapa versi secara berdampingan. Konsumen yang berintegrasi dengan API v1 Anda membaca dokumen v1 yang akurat bahkan setelah v2 dirilis. Versioning terhubung dengan cabang dan riwayat perubahan, sehingga evolusi API, dan dokumennya, tetap terlacak. Ini mencakup pengujian versioning dan jejak audit.

Tidak satu pun dari ini akan menghentikan TeamPCP untuk menyusupi laptop pengembang. Namun, ini berarti hal yang berbeda: jawaban yang jelas tentang siapa yang dapat membaca dokumen Anda, apakah versi yang diterbitkan sesuai dengan desain Anda, dan apa yang berubah seiring waktu. Itulah audit yang seharusnya mendorong Anda untuk dilakukan setelah pelanggaran GitHub.

Membandingkan Opsi Hosting Dokumentasi

Perbandingan cepat pendekatan umum terhadap empat properti keamanan.

Tidak ada baris yang benar secara universal. GitHub Pages Publik adalah pilihan yang baik untuk API publik dengan pipeline yang terkunci. Self-hosting cocok untuk tim dengan persyaratan residensi atau isolasi yang ketat; perbandingan dokumen API yang di-host sendiri kami dan perbandingan Scalar vs SwaggerHub vs Apidog menjelaskan pertukaran tersebut secara rinci. Intinya adalah memilih dengan sengaja berdasarkan empat properti, bukan mewarisi pengaturan dari tiga tahun lalu dan tidak pernah melihatnya lagi.

Kesimpulan

Pelanggaran GitHub bukanlah alasan untuk meninggalkan docs-as-code atau tidak mempercayai GitHub. Ini adalah pengingat untuk mengaudit permukaan yang diabaikan oleh sebagian besar tim: di mana dokumentasi API Anda berada dan apakah itu dapat dirusak.

Langkah selanjutnya: daftar setiap tempat dokumen API Anda diterbitkan, periksa masing-masing terhadap empat properti, dan tutup celah mana pun yang paling lebar. Jika kontrol akses adalah celahnya, unduh Apidog dan terbitkan dokumen satu proyek dengan kata sandi atau daftar izin email untuk melihat bagaimana lapisan terkelola menanganinya.