Implementasi Swagger UI pada Azure Function v2 dengan Menggunakan Swashbuckle
Aplikasi perlu dilengkapi dengan dokumentasi. Membuat dokumentasi yang terpisah dari aplikasi menciptakan resiko inkonsistensi, utamanya saat aplikasi dimodifikasi. Cara yang lebih baik adalah dengan membuat dokumentasi langsung di dalam aplikasi. Swagger adalah salah satu documentation tools yang banyak dipergunakan untuk keperluan ini.
Pada kesempatan ini, saya akan mempraktikkan cara membuat Swagger UI untuk sebuah proyek Azure Function v2 dengan menggunakan netcore 3. Proyek contoh berisi tiga fungsi, yaitu dua fungsi dengan method GET dan satu fungsi dengan method POST. Struktur dari proyek contoh dapat dilihat dari gambar dibawah.
Instalasi Package AzureFunctions.Extensions.Swashbuckle
AzureFunctions.Extensions.Swashbuckle merupakan package yang akan kita gunakan. Package ini dibuat oleh yu_ka1984 dan dapat mempermudah kita dalam pembuatan Swagger UI. Untuk melakukan instalasi package, kita dapat menggunakan “Manage NuGet Package…” yang sudah disediakan oleh Visual Studio. Untuk melakukannya, klik kanan pada project (dalam contoh klik kanan pada “SwaggerUIExample”) lalu klik pada “Manage NuGet Package…”. Setelah itu klik “Browse” dan cari AzureFunctions.Extensions.Swashbuckle pada kotak pencarian. Lakukan instalasi AzureFunctions.Extensions.Swashbuckle dan kita siap untuk menggunakan package tersebut.
Menambahkan Swashbuckle pada Startup.cs
Agar anotasi yang ada pada package AzureFunctions.Extensions.Swashbuckle bisa kita gunakan, kita perlu menambahkan sebuah Class bernama Startup.cs. Kalau pada proyekmu sudah ada, maka dapat menyesuaikan dari Startup.cs yang akan dipraktikkan disini. Isi dari Startup.cs dapat dilihat dibawah:
Penggunaan Swashbuckle pada Proyek
Setelah menambahkan Swashbuckle pada Startup.cs di proyek, selanjutnya kita perlu membuat HTTP Trigger untuk generate Swagger Json dan juga HTTP Trigger membuat visualisasi dari Swagger Json-tersebut (Swagger UI). Untuk melakukannya, kita dapat membuat sebuah Azure function baru di dalam proyek kita. Isi dari azure function tersebut dapat seperti ini:
Setelah itu kita dapat menjalankan aplikasi Azure Function kita dan melihat hasil Swagger UI yang terbuat, dapat dilakukan dengan mengakses http://localhost:7071/api/swagger/ui. catatan: gunakan port yang sesuai.
Meng-exclude API dari Swagger UI
Dari gambar sebelumnya kita melihat bahwa terdapat dokumentasi API dari SwaggerJson dan Swagger UI. Untuk menghilangkannya, tambahkan anotasi [SwaggerIgnore] pada API yang tidak kita inginkan untuk tampil di Swagger UI. Seperti pada contoh berikut:
Setelah menambahkan [SwaggerIgnore], maka dokumentasi API akan menghilang dari Swagger UI.
Membuat Dokumentasi Request Body dan Response dari API
Hasil dari dokumentasi diatas masih sangat sederhana, dimana hanya ada URL dari API yang ada dan response default yang merupakan string. Untuk menambahkan contoh bentuk object dari Response API kita dapat menambahkan anotasi
[ProducesResponseType((int)HttpStatusCode.<ResponseType>, Type = typeof(<ResponseObject>))]
pada fungsi yang diperlukan.
Untuk membuat dokumentasi dari Request Body yang diperlukan oleh API, kita butuh menambahkan sebuah anotasi pada bagian parameter di Azure Function. Kita harus menambahkan
[RequestBodyType(typeof(<RequestBodyObj>), <Description>)]
sebagai anotasi pada HttpRequest.
Hasil code yang sudah menambahkan dokumentasi Response API dan Request Body untuk API dapat dilihat dibawah ini:
Pada source code diatas, kita menambahkan dokumentasi Request Body dimana API tersebut harus menerima sebuah Request Body yang isi datanya seperti pada object UserData. Sedangkan API tersebut akan memberikan Response berupa object FunctionResponse jika status code OK (200) dan memberikan Response berupa string apabila status code BadRequest (400) atau NotFound (404). Tampilan dari Swagger UI akan menjadi seperti berikut.
Membuat Dokumentasi Query Parameter dan Path Parameter pada Method GET
Untuk Path Parameter, Swashbuckle sudah secara otomatis membuat dokumentasi untuk kita, namun tidak untuk Query Parameter. Untuk menambahkannya, kita perlu menambahkan anotasi [QueryStringParameter(<queryAttribute>, <queryAttrDesc>)] pada fungsi yang membutuhkannya. Contoh source code dapat dilihat dibawah ini:
Pada source code diatas, terlihat bahwa API tersebut memiliki dua Path Parameter yaitu name dan age serta dua Query Parameter yaitu message dan count. Hasil yang ditampilkan pada Swagger UI adalah sebagai berikut:
Membuat Dokumentasi Header yang Diperlukan pada Sebuah API
Untuk beberapa API terkadang memerlukan header tertentu. Seperti pada saat kita menggunakan JWT token sebagai media otentikasi dan otorisasi untuk seorang user. Untuk membuat dokumentasi dari header pada sebuah API, kita dapat menambahkan anotasi
[RequestHttpHeader(<headerAttrName>, isRequired: <boolean>)]
pada fungsi yang membutuhkannya. Berikut merupakan contoh source code yang mengimplementasikannya:
Hasil yang ditampilkan pada Swagger UI akan menjadi seperti berikut:
Selesai sudah proses bagaimana cara membuat Swagger UI untuk sebuah proyek Azure Function. Untuk source code yang digunakan dalam artikel ini dapat dilihat pada: Github. Package AzureFunctions.Extensions.Swashbuckle merupakan package yang dibuat oleh yu_ka1984 dan source codenya dapat diakses pada: Github Package.
Selamat mencoba!!!
Tambahan:
Untuk pengimplementasian Swagger pada Azure Function v3 dengan .NET Core 3.1. proses pengerjaan sama, namun package yang digunakan adalah AzureExtensions.Swashbuckle. Package tersebut merupakan hasil fork dari AzureFunctions.Extensions.Swashbuckle namun sudah dimodifikasi sehingga bisa digunakan untuk Azure Function v3 dengan .NET Core 3.1.
Reference:
