Artikel 5Menit: MockUp dan Dokumentasi Restful API dengan Swagger

Untuk membuat Restful API yang berfungsi secara fungsional mengikuti requirement dan spesification pada real project membutuhkan waktu yang cukup lama, terutama untuk project yang memiliki banyak endpoint service dan mekanisme banyak service. Sementara developer perlu menyiapkan platform yang bisa digunakan untuk arsitektur microservice, mengharuskan koneksi antar service dapat berlangsung ketika service yang sesungguhnya telah selesai. Karena itu diperlukan mockup service atau dummy service yang bekerja mengikuti aturan seharusnya. Dalam pembuatan tiap service juga bisa dibuat paralel tanpa bergantung pada service lain yang belum jadi 100%, karena tiap service bisa langsung dihubungkan dengan mock up tanpa perlu service lain yang terkait sudah selesai.

Dan untuk memastikan setiap service berjalan sesuai dengan aturan yang ada di kebutuhan teknis, diperlukan juga sebuah dokumentasi service yang sekaligus bisa digunakan sebagai acuan dalam pembuatan service yang terkait. Dokumentasi yang berbentuk teks, dokumen, xml, json, yaml, sangat teknikal sehingga terkadang terlalu sulit dibaca oleh keseluruhan bagian tim development, karena itu bisa kita gunakan tampilan web dengan UI yang cukup cantik. Disinilah kita membutuhkan Swagger yang merupakan kakas gratis untuk membuat MockUp dan dokumentasi Restful API yang pastinya GRATIS..

(tampilan swagger ui yang cantik )

Apa Saja Yang Perlu Dilakukan?

Pertama dari semuanya adalah tentukan mau menggunakan swagger di web atau di desktop, karena swagger juga tersedia dalam bentuk aplikasi desktop dan web.

Langkah-langkah yang diperlukan adalah

1. Menentukan endpoint API
2. Menentukan objek transfer API (request dan response object)
3. Buat MockUp dan Dokumentasi dengan swagger editor

Langkah ketiga adalah langkah terpanjang, tergantung seberapa banyak endpoint yang akan dibuat.

Misalkan kita ingin membuat sebuah inventory service dengan keterangan sebagai berikut:

1. Sebuah inventory memiliki id, name, release date dan manufacturer yang terdiri dari phone, name, homepage.
2. Terdapat keperluan untuk membuat service yang dapat melihat seluruh inventory, sebuah inventory berdasarkan id, membuat inventory, mengubah inventory yang ada, dan menghapus inventory

Maka endpoint yang kita perlukan adalah sebagai berikut:

List endpoint

Setelah membuat daftar endpoint yang perlu dibuat selanjutnya adalah membuat daftar objek yang akan digunakan sebagai response sebagai berikut:

1. Inventory Item

Inventory Item Object

2. Manufacturer

Mnufacturer Object

Setelah langkah pertama dan kedua sudah dilakukan, maka saatnya melakukan langkah ketiga yang paling lama.

Membuat Tampilan Swagger dengan Swagger Editor

Tampilan swagger ini mengikuti aturan OpenAPI yang menjadi standar dalam mendefinisikan Rest API. Penulisannya bisa menggunakan YAML atau JSON, namun meskipun pada banyak kasus (misal di kubernetes) ditulis menggunakan YAML, pada database bentuk YAML ini akan di-convert dalam bentuk JSON dan disimpan di database dalam bentuk JSON.

Pertama yang harus dilakukan adalah membuka swagger editor, kita bisa melihat contoh script yaml contoh Pet Store yang menjadi template awal. Namun pada tutorial ini kita akan membuat untuk Inventory Service. Dimulai pada bagian header dan keterangan yang merupakan bagian paling atas dari dokumentasi swagger.

Tampilan header

Berikut ini adalah tampilan YAML untuk menghasilkan header seperti di atas:

Di bagian paling bawah dari file YAML, tambahkan model sebagai berikut:

Gunakan YAML pada bagian “definition” di bawah ini untuk menghasilkan model Inventory Item dan Manufacturer seperti di atas.

Setelah model tersebut ditambahkan, kemudian buatlah endpoint-endpoint yang ingin digunakan pada bagian “path”. Hasilnya akan seperti berikut.

Perlu diingat bahwa urutan pembuatannya adalah header lalu model dan terakhir endpoint, karena endpoint-nya akan melakukan referensi ke model sebagai data input atau output.

Untuk membuat semua hal di atas gunakan file swagger selengkapnya bisa diunduh di sini.

Hal terakhir yang perlu dilakukan adalah klik “Generate Server” dan pilih nodejs maka akan dihasilkan file zip yang berisi sebuah API dummy yang menggunakan bahasa pemrograman javascript. Kemudian ekstrak zip tersebut dan jalankan pada konsol dengan mengetik npm start (jika sudah terinstall npm di komputer, kalau belum install dari sini)