API Documentation using Scramble - Official Blog of Akhdani Reka Solusi

Halo, Kreatif Reader! Pada artikel ini, saya akan membahas mengenai salah satu tools untuk mendokumentasian API, yaitu Scramble. Sebelum kesana, mari kita pahami terlebih dahulu apa itu API serta mengapa API perlu didokumentasikan dengan baik.

API (Application Programming Interface) merupakan interface yang dibangun oleh tim pengembang untuk menyimpan function atau aturan sehingga memungkinkan adanya interaksi dan komunikasi antar aplikasi yang berbeda. Sederhananya, API dapat memudahkan developer untuk mengkonsumsi data dari sistem lain yang terintegrasi, tanpa harus menulis ulang code.

API sendiri memiliki beberapa jenis arsitektur, salah satunya adalah REST API. Pada gambar berikut ini, adalah ilustrasi cara kerja REST API sebagai jembatan antar aplikasi atau platform. rest-api-model

Seperti yang telah disebutkan sebelumnya, bahwa API berisikan function atau aturan, maka perlu dilakukan pendokumentasian yang baik, agar developer dapat dengan mudah memahami fungsi serta cara penggunaan setiap baris kodenya. Idealnya, dokumentasi API berisikan informasi detail API, termasuk fungsi, parameter, tipe pengembalian, kelas, dan lainnya, dalam urutan yang logis.

Salah satu tools yang dapat digunakan untuk dokumentasi API adalah Scramble. Mengutip dari dokumentasi resminya, Scramble merupakan generator otomatis untuk mendokumentasikan API pada Laravel. Scramble menggunakan format penulisan OpenAPI 3.1.0, dimana penyajiannya direpresentasikan menggunakan format JSON atau YAML, seperti contoh di bawah ini.

{
 "name": "John Doe",
 "email": "john.doe@example.com",
 "password": "password"
}

Dokumentasi yang dihasilkan kemudian dibungkus dengan User Interface Stoplight Elements seperti gambar berikut ini:

Untuk melakukan installasi dan setup Scramble, dibutuhkan minimal PHP versi 8.1 serta Laravel versi 8.

Langkah-langkah yang harus dilakukan untuk melakukan generate dokumentasi menggunakan Scramble adalah:

1. Pastikan Anda telah memiliki endpoint API

2. Instalasi Scramble via composer

composer require dedoc/scramble

3. Instalasi Database Abstraction Layer (DBAL) via composer

composer require doctrine/dbal

4. Publish file konfigurasi

php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"

5. Tambahkan routes pada folder routes/api.php sesuai endpoint yang telah dibuat, contohnya seperti berikut:

Route::group(['prefix' => 'auth'], function () {
 Route::post('login', [AuthController::class, 'login'])->name('auth.login');
 Route::post('register', [AuthController::class, 'register'])->name('auth.register');

 Route::group(['middleware' => 'auth:sanctum'], function () {
 Route::post('logout', [AuthController::class, 'logout'])->name('auth.logout');
 });
});

6. Konfigurasi Scramble pada folder config/scramble.php untuk menambahkan API version, deskripsi, serta informasi lain yang dibutuhkan

7. Tambahkan Authentication Header pada folder app/Providers/AppServiceProvider.php untuk mengatur izin akses pada environment lain, contohnya seperti berikut:

public function boot()
{
   Scramble::extendOpenApi(function (OpenApi $openApi) {
     $openApi->secure(
        SecurityScheme::http('bearer', 'JWT')
     );
   });
}

8. Dokumentasi API telah siap diakses sesuai routes yang telah dibuat.

Reference:
[1] PERANCANGAN APLIKASI PEMROGRAMAN ANTARMUKABERBASISWEB MENGGUNAKAN GAYA ARSITEKTUR REPRESENTASI UNTUK SISTEM PRESENSI SEKOLAH
[2] https://scramble.dedoc.co/
[3] Membuat Dokumentasi API dengan Scramble pada Laravel | Medium

Leave a Reply Cancel reply