Pada blog kali ini saya akan membahas service docs. Saat ini API yang kita buat belum memiliki dokumentasi. Kita akan membuat dokumentasi bagaimana cara mengakses API yang telah kita buat.

Mempersiapkan Docs Generator

Untuk membuat docs generator kita akan menggunakan swagger-ui (https://swagger.io/tools/swagger-ui/). Pertama kita install terlebih dahulu swagger-php plugins nya menggunakan composer seperti berikut.

composer require zircote/swagger-php

Selanjutnya membuat artisan command file. Buat file app/Console/Commands/SwaggerDocScanner.php

Buka file app/Console/Kernel.php, tambahkan code berikut pada variabel commands.

Untuk menjalankan artisan command SwaggerDocScanner dan menggenerate docs, pada terminal/CommandPrompt jalankan command php artisan swaggerdoc:scan, command teserbut akan membuat file public/swaggerdoc.json. Saat ini kalau dijalankan, command ini bakal error, karena kita belum mendefiniskan anotasi docs nya.

Untuk tampilan User Interface nya kita perlu mebuat file html di public folder. Buat file public/api-docs.html, code nya seperti berikut.

Atau anda juga bisa copy melalui link berikut https://github.com/sunnyagarwal008/setup-swagger-ui-in-one-page/blob/master/swagger-ui.html.

Jalankan servernya, kemudian akses endpoint http://localhost:8000/api-docs.html, maka tampilan akan seperti berikut.

Membuat Dokumentasi API (Get Request)

Kita akan membuat API dokumentasi untuk endpoint /register. Buka file app/Http/Controllers/Controller.php, tambahkan code dibawah ini.

Buka file app/Http/Controllers/Public/PostsController.php, tambahkan code dibawah ini.

Pada terminal/CommandPrompt jalankan command di bawah ini.

php artisan swaggerdoc:scan

Setiap kali anda mengubah anotasi docs, harus menjalankan command tersebut supaya bisa update docs nya.

Pada browser buka http://localhost:8000/api-docs.html

Jika di click pada button GET, maka tampilanya akan seperti berikut.

Silahkan dicoba dengan mengklik button Try it out.

Membuat Dokumentasi API (Post Request)

Kali ini kita akan membuat t API dokumentasi untuk endpoint /register. Untuk membuat dokumentasi API mengenai Post Request, buka file App/Http/Controllers/AuthController.php dan tambahkan code berikut.

Pada terminal/CommandPrompt jalankan command di bawah ini. Setiap kali anda mengubah anotasi docs, harus menjalankan command di bawah ini supaya bisa update
docs nya.

php artisan swaggerdoc:scan

Akses kembali endpoint http://localhost:8000/api-docs.html

Jika di click pada button POST, maka tampilannya akan seperti berikut.

Silahkan dicoba dengan mengklik button Try it out.

Membuat dokumentasi untuk semua endpoint

Pertama kita akan membuat dokumentasi untuk endpoint user login, tambahkan script berikut pada AuthController.php.

Jalankan command berikut pada terminal.

php artisan swaggerdoc:scan

Akses kembali http://localhost:8000/api-docs.html, maka akan muncul endpoint untuk user login.

Silahkan dicoba dengan mengklik button Post lalu Try it out.

Jika berhasil maka akan muncul respon token yang akan kita gunakan untuk authentication.

Tambahkan script berikut pada Controller.php untuk menambahkan fitur authorization agar semua endpoint post yang akan kita akses perlu mengirimkan token terlebih dahulu.

Jalankan kembali command berikut.

php artisan swaggerdoc:scan

Maka ketika mengakses http://localhost:8000/api-docs.html, akan muncul button Authorize sebagai akses token yang kita gunakan untuk mengakses endpoint.

Selanjutnya kita akan membuat dokumentasi untuk function show tambahkan script berikut pada Public\PostsController.php.

---

Jalankan kembali command berikut.

php artisan swaggerdoc:scan

Kemudian akses kembali http://localhost:8000/api-docs.html, maka akan muncul endpoint baru.

Coba dengan klik button GET, lalu Try it out.

Dokumentasi untuk endpoint /posts

Sebelumnya kita baru membuat dokumentasi pada endpoint /public/posts, selanjutya kita akan akan membuat dokumentasi untuk endpoint /posts, tambahkan script2 berikut pada setiap function di controller App\Http\Controllers\PostsController.php.

Seperti biasa jalankan command berikut.

php artisan swaggerdoc:scan

Maka akan muncul endpoint-enpoint berikut.

Sekarang tinggal kita test satu per satu endpoint Posts, namun sebelum itu kita perlu login terlebih dahulu untuk mendapatkan access token. Klik endpoint User login, klik Try it out, masukkan value email dan password yang valid, lalu execute.

Jika berhasil maka akan muncul respon access token.

Klik Authorize, dan masukkan access token nya.

Pertama kita coba akses endpoint get posts, klik Try it out, bisa dengan mengirimkan parameter page ataupun tidak, lalu execute.

JIka berhasil respon akan seperti berikut.

Kedua kita coba create new posts, klik Try it out, lalu ketikkan value yang akan dikirimkan, kemudian execute.

Jika berhasil maka respon akan seperti berikut.

Ketiga ktia coba akses endpoint Get posts by id denga mengirimkan parameter berupa id posts.

JIka berhasil respon akan seperti berikut.

Keempat kita coba akses endpoint Update posts, dengan mengirimkan parameter id, dan value untuk update data posts.

Jika berhasil maka respon akan seperti berikut.

Terakhir kita coba akses endpoint Delete post by id dengan mengirimkan paramter id.

Jika berhasil maka respon akan seperti berikut.

Sekian tutorial membuat dokumentasi API menggunakan swagger ini, selamat mencoba

Hatur Nuhun

Di tutorial bagaimana cara membuat aplikasi client. Sebelumnya kita membuat  aplikasi web service REST API server, kali ini kita akan buat aplikasi client nya dan bagaimana cara mengakses data dari server tersebut.

Pertama install terlebih dahulu project lumen client app menggunakan composer seperti dibawah ini.

Disini saya membuat project dengan nama lumen-client-app, kemudian masuk ke directory aplikasi client tersebut, dan jalankan servernya pada port 9000.

Coba akses localhost:9000 pada browser, jika tampilannya seperti dibawah ini maka telah berhasil.

Membuat Fungsi Untuk Mengakses Web Service JSON (Get Request)

Setelah jalankan servernya, kita buka project lumen-client-app pada text editor kita, buka file routes/web.php dan buat routing seperti berikut.

Buat controller dengan nama app/Http/Controllers/PostsController.php, kemudian buat function getRequestJson dengan code nya seperti dibawah ini.

Masuk kedalam folder resource/views, buat sebuah folder dengan nama posts kemudian buat file getRequestJson.php di dalam folder posts tersebut.

Dalam getRequestJson.php ini kita akan membuat struktur HTML, tambahkan script berikut di dalam getRequestJson.php.

Sebelum kita test di browser tentunya kita perlu menjalankan terlebih dahulu server web servicenya. Teman-teman bisa masuk ke project sebelumnya, yaiut “php-lumen-service-app” dan buka terminalnya, disini saya menggunakan text editor visual studio code yang di dalamnya sudah tersedia fitur terminal untuk memudahkan kita dalam menjalankan servernya. Untuk menjalankan web service nya kita gunakan port 8000 seperti berikut.

Sekarang kita masuk lagi ke project lumen-client-app, untuk mengecek terlebih dahulu apakah data nya sudah berhasil diambil dari web service kita bisa menggunakan function dd() atau biasa disebut dump, kita lihat isian data dari respon dengan menambahkan function dd() sebelum return view.

Lalu akses endpoint http://localhost:9000/posts/get-request-json, jika respon nya seperti berikut maka data telah berhasil di get dari web service.

Bisa dilihat isi dari response adalah 4 data berbentuk array yang didapat dari web service. Selanjutnya kita hapus kembali function dd tersebut atau bisa di berikan comment saja, kemudian akses kembali endpoint http://localhost:9000/posts/get-request-json, jika berhasil tampilan akan seperti berikut.

Membuat Fungsi Untuk Mengakses Web Service XML (Get Request)

Sekarang kita akan membuat request client yang sama, namun menggunakan format XML. Tambahkan routing baru pada file web.php.

Buat function baru getRequestXml() pada PostsController.

Untuk format xml kita perlu menginstall terlebih dulu library simple xml.

composer require ext-simplexml

Seperti biasa sebelum kita akses endpoint http://localhost:9000/posts/get-request-xml, kita lakukan dump terlebih dahulu untuk melihat isian dari response, jika tampilan seperti berikut maka sudah berhasil di get.

Hapus kembali function dump atau berikan comment, lalu akses kembali endpointnya.

Membuat Fungsi Untuk Mengakses Web Service JSON (Post Request)

Sekarang kita akan melakukan post data atau mengirimkan data dari client, pertama buat terlebih dahulu routing nya.

Kemudian buat function postRequsetJson() pada PostsController.

Selanjutnya kita buat tampilan view pada folder posts/postRequestJson seperti berikut.

Jika berhasil, maka tampilan akan seperti berikut.

Cek juga di database kita apakah data tersebut sudah berhasil di create atau belum.