Membuat Dokumentasi API di Adonis

Published in

AdonisID

4 min readMar 5, 2018

Source: Adi Rahman — http://www.ceritadikit.com

Banyak tools yang dapat digunakan untuk membuat dokumentasi API, beberapa diantaranya dapat langsung menjalankan/melakukan request terhadap API tersebut. Beberapa tools yang banyak digunakan untuk mendokumentasikan API diantaranya adalah swagger, apiary, APIDoc, dan Postman. Beberapa tools yang saya sebutkan memiliki kelebihan dan kekurangannya masing-masing, seperti swagger yang dapat melakukan uji coba terhadap API yang dibuat pada halaman dokumentasinya.

Untuk memudahkan pekerjaan, kita akan menggunakan package adonis-swagger yang sudah saya buat. Package ini support pembuatan dokumentasi dengan format JS dan YAML. Secara default package tersebut dapat membaca dokumentasi di folder app dan di file start/routes.js dengan format JS. Kalau saya mau membuat dokumentasi tapi di folder dan file yang terpisah dari source codenya gimana? 🤔

Kamu cukup ubah file config/swagger.js, supaya mengarah ke file maupun folder yang mau dijadikan tempat menulis dokumentasinya. Misalnya dokumentasi akan dituliskan di dalam folder docs, maka kamu tinggal ganti atau hilangkan simbol komentar pada kode contoh yang ada di file config/swagger.js , kemudian hapus kode apis: []. Kurang lebih seperti berikut:

Konfigurasi tersebut akan membaca secara rekursif seluruh file dengan format .yml dan .js di dalam folder docs.

Instalasi

Untuk memasang package adonis-swagger, berikut langkah-langkah instalasinya:

Buat proyek Adonis

Buat proyek baru dengan perintah

adonis new adonis-swagger-example

Kemudian masuk ke folder proyek dengan perintah

cd adonis-swagger-example

Install package adonis-swagger

Untuk menginstall adonis-swagger, gunakan perintah berikut ini

adonis install adonis-swagger

Dengan menggunakan perintah adonis install <NAMA_PACKAGE>, maka otomatis menjalan fungsi post-install sesuai instruksi yang didefinisikan pada fileinstructions.js. Dimana perintah setelah instalasi package adonis-swagger adalah membuat file konfig dan menyalin assets untuk interfacenya swagger. Install menggunakan perintahadonis install adonis-swagger secara otomatis melakukan export file config dan assets ke working directory, atau dapat menggunakan perintah adonis swagger:export untuk melakukan export tersebut.

Mendaftarkan SwaggerProvider ke dalam providers list

Tambahkan 'adonis-swagger/providers/SwaggerProvider' ke dalam array providers di file start/app.js. Kurang lebih seperti berikut:

Untuk membuat dokumentasi, harus mengikuti spesifikasi dari swagger bisa cek pada link https://swagger.io/specification/. Jika mengikuti artikel dari awal, maka kita dapat menuliskan dokumentasi dengan format komentar JavaScript di routes.js dan folder app (didefinisikan pada masing-masing function dari controller), dan juga dapat mendefinsikan dokumentasi menggunakan format JS maupun YAML di folder docs.

Membuat dokumentasi di Route

Untuk membuat dokumentasi di routes.js cukup menuliskan swagger spesification, seperti contoh berikut:

Pada file routes.js di atas, kita mendefinisikan path APInya terlebih dahulu, kemudian methodnya, lalu contoh response pada saat requestnya sukses. Untuk contoh tidak wajib dituliskan, namun supaya saat mendistribusikan API lebih gampang dibaca alangkah baiknya mendefinisikan contoh responsenya. Langkah selanjutnya adalah menjalankan development server dengan perintah adonis serve --dev, kemudian buka di browser halaman http://localhost:3333/docs, maka akan tampil halaman dokumentasi seperti yang sudah didefinisikan pada routes.js yang sudah kamu buat.

Pada halaman tersebut kamu dapat mencoba menambahkan authorization header (seperti token yang didapat setelah login), untuk beberapa API yang memerlukan otorisasi. Dan juga dapat mencoba API dengan memilih API yang mau dicoba, kemudian klik tombol Try it out, lalu menekan tombol Execute. Pada halaman tersebut akan menampilkan response dari API (di atas contoh response), seperti gambar berikut ini.

Mudah kan dalam mendokumentasikan API? Jangan malas lagi ya 😜

Aplikasi saya ada sekitar 1.000.000 API, alhasil file routes.js saya membengkak, malah jadi pusing bacanya 😖

Untuk menangani permasalahan tersebut, kamu juga dapat mendefinisikan dokumentasi pada controllernya masing-masing asal masih sesuai dengan swagger spesificationnya. Misalnya saya menambahkan 2 API baru, namun menuliskan dokumentasinya di controllernya. Seperti contoh berikut:

File routes.js

File TestController.js

Maka ketika kita refresh halaman http://localhost:3333/docs hasilnya seperti berikut:

Tinggal melihat spesifikasi APInya dan mencoba seperti sebelumnya.

Error nih saat coba POST /api/hello, error karena Adonis secara default memproteksi semua URL dengan CSRF Protection (Cross-Site Request Forgery). Untuk pembuatan API cukup disable URL yang diawali dengan /api saja, silahkan ubah file config/shield.js seperti berikut:

Kalo saya gak suka buat dokumentasi di kodenya langsung, lebih suka dipisahkan dari kodenya. Apa bisa? 🤔

Jawabannya: Bisa!

Sebelumnya kan sudah melakukan konfigurasi untuk dapat membaca format YAML dan JS di folder docs, sekarang mari kita coba menambahkan API lagi dan membuat dokumentasi di folder docs.