Haloo kreatif reader.. kali ini aku mau bahas tentang Dokumentasi API L5 Swagger pada Laravel.
Dokumentasi API adalah dokumentasi yang berisi kumpulan panduan penggunaan API terhadap suatu program atau aplikasi. Dokumentasi API ini digunakan sebagai acuan untuk mendeskripsikan API secara menyeluruh sehingga penggunaan API dapat mudah dipahami oleh seluruh tim pengembang ataupun pengembangan lain untuk pemeliharaan aplikasi selanjutnya.
Salah satu tools yang dapat digunakan untuk mendokumentasikan API adalah Swagger. Swagger merupakan framework populer yang digunakan untuk OpenAPI Specification (OAS). Penggunaan swagger dapat menyederhanakan proses dokumentasi API secara interaktif. Dokumentasi yang dihasilkan dapat dengan mudah dipahami oleh pengguna teknis maupun non-teknis.
Saat ini swagger sudah dapat digunakan langsung pada framework Laravel dalam bentuk package L5 Swagger yang bekerja dengan mengadaptasi swagger-php dan swagger-ui.
Untuk melakukan instalasi dan setup L5 Swagger pastikan laravel dan composer sudah terinstall di laptop pengguna. Setelah itu ikuti langkah-langkah instalasi package l5swagger berikut ini:
1. Install package l5 swagger melalui composer
composer requires darkonline/l5-swagger tymon/jwt-auth
2. Publish file konfigurasi L5Swagger
php artisan vendor: publish --provider "L5Swagger\L5SwaggerServiceProvider"
3. Konfigurasi Swagger
Buka file config/l5-swagger.php dan sesuaikan pengaturan misalnya dengan mengonfigurasi path API documentation, keamanan, dan lainnya.
4. Tambah anotasi swagger ke Route dan Controllers
Contoh penggunaan anotasi pada route:
/**
* @OA\Get(
* path="/api/user",
* summary="Get a list of users",
* tags={"Users"},
* @OA\Response(response=200,
* description="List of users",
* ),
* )
*/
Contoh penggunaan anotas pada contollers
/** * @OA\Info( * title="Swagger with Laravel", * version="1.0.0", * ) * @OA\SecurityScheme( * type="http", * securityScheme="bearerAuth" * scheme="bearer" * bearerFormat="JWT" * ) */
5. Generate dokumentasi Swagger
php artisan l5-swagger:generate
Perintah ini akan menghasilkan file JSON swagger dan secara default menyimpannya di direktori publik.
6. Akses halaman swagger dengan mengunjungi url yang telah dibuat pada file konfigurasi. Contohnya ‘http://your-app-url/api/documentation’
Berikut ini contoh tampilan hasil generate dokumentasi swagger:
Dengan penggunaan l5 swagger yang mudah diimplementasi ini, diharapkan dapat mendorong kolaboarasi yang lebih baik dan mempercepat pengembangan API pada aplikasi laravel yang dibuat.
Referensi:
Upadhyay, Mayur. (2024, January 04). Laravel Swagger Integration: A Step-by-Step-Guide. WPWEB Infotech.
Kolodii, Ivan. (2020, May 10). How to write Swagger Documentation for Laravel API. Tips & Example. Medium.