OpenAPI (Swagger)

Dari sekian hal yang pernah saya ketahui, belum tentu semuanya saya eksplorasi. Dari sekian hal yang pernah saya eksplorasi, belum tentu semuanya saya gunakan. Dari sekian hal yang saya gunakan, belum tentu semuanya saya cocok. Dari sekian hal yang saya cocok, belum tentu semuanya saya nikahi.

Dancuukkkk ujung2nya itu lo… 😭

Pembaca tulisan ini mayoritas jomblo apa yak, sensitip amat… 🤔

Dokumentasi API

Kalau kalian punya REST-API, dan ingin membuka akses untuk orang lain (teman, rekan kerja, mitra perusahaan, dll). Maka cara termudahnya adalah dengan mendokumentasikan dan mempublikasikannya.

Pada dasarnya, struktur dokumentasi bisa ber-macam2. Cara berkomunikasi dengan API-nya pun juga bisa beraneka ragam. Dari berbagai kemungkinan itu lah maka muncul upaya standarisasi dokumen. Salah satunya adalah melalui konsorsium para ekspert di dunia per-API-an, yang menghasilkan standarisasi bernama OpenAPI.

OpenAPI

Dimana-mana, yang namanya standarisasi pasti hanya membuahkan standar. Jadi jangan sampai terpeleset dengan membayangkan OpenAPI adalah sebuah software yak. Jadi kalau kalian cek isi websitenya di sini, yang kalian temukan hanya bahasan tentang spesifikasi2 aja. Apakah saya paham semuanya? Jelas enggak dongs. 🙃

Swagger UI

Salah satu dan satu2nya output dari OpenAPI yang akan saya bahas di sini adalah Swagger UI. 😶‍🌫️

Iya iya, sesuai judul… 😓

Gambaran besarnya begini. Melalui OpenAPI yang sudah kita definisikan, nantinya kita bisa menghasilkan halaman web yang dapat diakses oleh konsumen API kita. Swagger UI adalah salah satu bentuk atau format outputnya. Contoh hasilnya bisa kalian lihat di bawah ini.

Sependek yang saya tahu, kayaknya Swagger UI ini adalah output yang paling mudah dihasilkan. Mengingat dia merupakan produk open source. Sehingga banyak diadopsi oleh para pengembang generator open source juga.

PHP dan OpenAPI

Karena saya setiap harinya mainan PHP, maka kita kerucutkan bahasan kita ke konteks PHP yak.

Nah, sebelumnya kita sudah tahu apa itu OpenAPI. Kita sudah tahu salah satu outputnya adalah Swagger UI. Selanjutnya kita akan masuk ke proses di antaranya.

Seperti yang sudah saya singgung sebelumnya mengenai masifnya adopsi OpenAPI di wilayah open source. Di bahasa PHP, mudah saja kita temukan pengembang yang membuat generator untuk menghasilkan Swagger UI, misalnya swagger-php. Yang terintegrasi dengan framework pun juga ada, misalnya NelmioApiDocBundle untuk Symfony dan L5-Swagger untuk Laravel. Yang totalitas sebagai platform API juga ada, yaitu API Platform.

Dari yang biasa sampai yang siap pakai sudah ada gaes. Seenak itu jalan untuk menjadi tukang kode di masa kini. 🙃

OpenAPI di PHP

Tapi, kata siapa menggunakan API Platform enak? Siapa yang bilang pakai Nelmio atau L5-Swagger mudah? Menjadi tukang kode gak semulus paha LC gaes. 😶‍🌫️

Doctrine Annotation

Bagi kalian yang masih menggunakan PHP 7.4, tidak ada cara yang lebih baik selain menggunakan annotation. Annotation merupakan produk dari Doctrine yang memanfaatkan blok dokumentasi di PHP untuk mendeklarasikan suatu fungsi dari suatu class. Yang selanjutnya dapat dibaca dan digunakan sebagaimana class PHP pada umumnya. Konsep annotation sendiri sebenarnya sudah diadopsi jauh2 oleh Java. Dan annotation merupakan salah satu produk ambisi Doctrine untuk dapat mengadopsi sebanyak mungkin kebaikan dari Java. Salut gaes… ☕️

/**
 * Ini contoh blok dokumentasi
 */

Dalam konteks OpenAPI, annotation digunakan untuk mendeklarasikan penggalan2 struktur spesifikasi OpenAPI. Yang nantinya dibaca dan dirangkai menjadi satu spesifikasi utuh. Spesifikasi utuh itu lah yang sebenarnya dikonsumsi PHP untuk dijadikan halaman Swagger UI.

/**
 * Di bawah ini contoh syntax Nelmio di annotation
 * untuk membuat tag di swagger
 * @SWG\Tag(name="pet")
 */

Keren gaes… 🤯

Betul, mereka emang keren… 😆

Btw kalau kalian anak Symfony, ini mestinya udah makanan sehari-hari. 🙃

PHP Attribute

Mungkin tanpa adanya keberhasilan dan masifnya adopsi annotation dari Doctrine, PHP gak bakal punya gairah untuk menyediakan attribute deh. 🫣

Tapi gak tau lah ya, yang penting secara resmi PHP punya fitur yang fungsinya sama seperti annotation di Doctrine. Dengan adanya attribute di PHP, Doctrine juga secara resmi menghentikan dukungan di annotation.

Jadi kalau kalian mau buat OpenAPI di PHP 8.1 dengan Nelmio, kalian bisa memanfaatkan attribute ini gaes. Syntax attribute memang agak beda dengan annotation, tapi secara konsep sama persis.

// Di bawah ini contoh syntax Nelmio di attribute
#[OA\Tag(name: 'pet')]

Mengakses Swagger UI

Mendefinisikan spesifikasi OpenAPI sudah, dengan annotation atau attribute. Menghasilkan Swagger UI juga sudah, dengan bantuan Nelmio atau L5-Swagger. Maka selanjut adalah mempublikasikan project-mu gaes. Setelah dipublikasikan, konsumen REST-API-mu cukup mengaksesnya melalui web browser.

Yang perlu diingat, setiap alat yang kamu gunakan mungkin menghasilkan alamat Swagger UI yang berbeda. Misalnya Nelmio, alamat default-nya ada pada path /api/doc.

Penutup

Begitu kira2 gaes, secuil yang bisa saya bagikan kali ini. Semoga bisa meminimalisir ketidak tahuan para tukang kode di sekeliling kalian mengenai OpenAPI. Meskipun OpenAPI bukan lah kemampuan teknis inti dari REST-API, tapi pengalaman menggunakan OpenAPI tentunya merupakan nilai tambah yang cukup berarti.

Saya pribadi, gak pernah menyimpan di dengkul bagaimana cara membuat Swagger UI di PHP. Jadi kalau disuruh buat, pasti nengok ke contoh yang diberikan Nelmio atau L5-Swagger. Untuk kasus2 yang lebih detail, mau gak mau ya nengok ke spesifikasinya OpenAPI. 🥱

Oke cukup sekian gaes, nyok lanjut angkat LC-nya… Eh kopinya… ☕️