Mencoba Laravel OpenAPI (Swagger) document generator Scramble
Scramble adalah salah satu API documentation generator yang bisa digunakan pada Laravel untuk membuat dokumentasi API dari OpenAPI (Swagger). Scramble akan memindai setiap API endpoint yang ada pada routes lalu membuatkan dokumentasi dari API yang ada.
Pengenalan
OpenAPI Specification (OAS)
OAS adalah format deskripsi API untuk RESTful API. OAS memungkinkan untuk melakukan deskripsi dari seluruh bagian API, meliputi :
- Endpoint yang tersedia dan operasinya (GET, POST dan lainnya)
- Parameter operasi untuk input dan output untuk setiap operasi
- Metode autentikasi
- Informasi kontak, lisensi dan informasi lainnya
Swagger
Swagger adalah serangkaian tools yang bisa digunakan untuk membantu melakukan desain, dokumentasi dan mengkonsumsi REST API dengan mengimplementasikan spesifikasi yang diterapkan dalam OpenAPI (OAS).
Scramble
Scramble adalah salah generator dokumentasi untuk OpenApi (Swagger) untuk Laravel. Dengan menggunakannya kita bisa membuat dokumentasi API tanpa perlu menuliskan banyak anotasi untuk endpoint yang dibuat.
Implementasi
Instalasi
Untuk menggunakannya, kita perlu melakukan instalasi dua package yang diperlukan. Selain itu karena kita akan memberikan beberapa konfigurasi tambahan, maka perlu untuk melakukan publish file konfigurasi dari Scramble.
- Instalasi package Scramble.
composer require dedoc/scramble2. Instalasi package Database Abstraction Layer (DBAL).
composer require doctrine/dbal3. Publish file konfigurasi.
php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider" --tag="scramble-config"Authentication API
Untuk keperluan endpoint autentikasi, kita akan membuat controller dan Form Request Validator.
- Authentication Controller
2. Login Form Request
2. Register Form Request
Category API
Untuk keperluan endpoint Category, kita akan membuat controller, Form Request Validator dan API Resource.
- Category Controller
2. Category Form Request
3. Category Resource
Post API
Untuk keperluan endpoint Post, kita akan membuat controller, Form Request Validator, Query Param Validator dan API Resource.
- Post Controller
2. Post Form Request
3. Post Query Parameter
4. Post Resource
Konfigurasi
Setelah membuat endpoint yang diperlukan, selanjutnya perlu untuk menambahkan route agar bisa terbaca oleh Scramble. Lalu kita juga akan menambahkan deskripsi mengenai API pada file konfigurasi Scramble. Dan terakhir perlu menambahkan konfigurasi untuk header autentikasi pada AppServiceProvider.
- API routes
2. Scramble Config
3. Authentication Header
Hasil
Home
Berikut adalah dokumentasi yang dibuat berdasar konfigurasi Scramble.
- Overview
Authentication API
Berikut adalah dokumentasi yang dibuat untuk Authentication API.
- Login
2. Register API
3. Logout API
Category API
Berikut adalah dokumentasi yang dibuat untuk Category API.
- List Category
2. Create Category
3. Show Selected Category
4. Update Category
5. Delete Category
Post API
Berikut adalah dokumentasi yang dibuat untuk Post API.
- List Post
2. Create Post
3. Show Selected Post
4. Update Post
5. Delete Post
Resource
Berikut adalah dokumentasi yang dibuat berdasarkan API resource.
- Category Resource
2. Post Resource
Penutup
Kata Penutup
Penggunaan Scramble sebagai API documentation generator bisa meringkas waktu yang diperlukan untuk menuliskan anotasi untuk dokumentasi API. Namun, hingga saat ini belum menemukan cara untuk menambahkan header selain untuk autentikasi. Selain itu, untuk membuat dokumentasi dari query paramater, perlu ditambahkan Form Request dan hanya bisa untuk endpoint dengan HTTP request method GET. Semoga tulisan kali ini bermanfaat. Sampai jumpa di tulisan selanjutnya. Salam.
