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
0 komentar:
Posting Komentar