[rojak-api] Better UI untuk spesifikasi API

[bobbypriam]

Kita saat ini menggunakan library raml2html untuk rendering HTML dari file RAML. Template defaultnya (yang bisa dilihat di sini) sebenernya "good enough", tapi interaksinya agak mengganggu (harus klik dan buka modal untuk bisa lihat contoh request dan response, dsb.).

Untungnya raml2html support custom templates dengan templating engine nunjucks. Kalau ada yang berminat membuatnya, silakan komentar di sini 😄

Salah satu referensi custom template yang open source: http://developer.officernd.com (source code)

Atau kita juga bisa menggunakan tool lain, misalnya http://raml2html.leanlabs.io. Apakah itu lebih bagus?

[reinarduswindy]

@bobbypriambodo belum ada yang kerjain ini kan? sya yang kerjain aja boleh?

[bobbypriam]

Belum ada mas @reinarduswindy, silakan! :smile: File yang berhubungan ada di direktori /rojak-api/spec ya. Kalau mau tanya-tanya silakan di issue ini atau slack hehe.

[reinarduswindy]

oke mas @bobbypriambodo . :smile:

[reinarduswindy]

Dokumentasi API nya sya menggunakan ApiDoc. Menurut sya lebih nyaman dilihat aja sih kalau pakai ini. Minta pendapatnya mas @bobbypriambodo @pyk Apa yang harus ditambahkan lagi atau ada yang perlu diganti? 😄

UI barunya jadi sprti ini https://rawgit.com/reinarduswindy/rojak/master/rojak-api/spec/public/apidoc/index.html

[pyk]

@reinarduswindy looks good! 👍

[bobbypriam]

@reinarduswindy Bagus! Overall saya suka presentasinya, semua ada di satu tempat dan navigasinya gampang. Ada beberapa pertanyaan sih:

1. Navigasi di kiri urutannya bisa kita tentuin ga ya?
2. Saya barusan ngeliat kodenya, apiDoc pakai bahasanya langsung ya (di kasus ini mas @reinarduswindy pakai JS). Di sini kita jadi punya dua source of truth, file raml dan file example-nya. Kayaknya mending salah satu aja ya... I don't mind kalo kita harus ngeganti RAML dengan yang lain sih. (Dan kalau emang pakai bahasanya langsung, mungkin ga ya pakai Elixir aja biar satu bahasa gitu hehe)
3. node_modules jangan dimasukin ke git mungkin mas 😄 biar ga kegedean reponya.
4. rojak-api/spec/index.js untuk apa ya?
5. Kalau sudah fix, mungkin butuh tambah dokumentasi juga file-file apa aja yang relevan dan gimana cara ngebuildnya.

Silakan buka PR supaya lebih enak diskusinya mas!

[reinarduswindy]

Oke mas @bobbypriambodo . Sya coba jawab pertanyaannya.

1. Navigasi di kiri syangnya saya belum temuin cara untuk atur urutannya sesuai dengan yang kita mau. Saya baca" dokumentasinya di http://apidocjs.com/, untuk fungsi ordernya memang blm disediakan. CMIIW :sweat_smile:
2. Seharusnya sih harus pakai Elixir mas @bobbypriambodo . Nanti sya coba benarin. Untuk file RAML sya hapus aja berarti?
3. node_modules nya sya hapus juga nanti mas. :smile:
4. index.js tadinya sya pakai sebelum sya pisah"in menurut masing-masing case (candidates, pairings, media, news) di rojak-api/spec/example dan saya lupa hapus filenya.
5. Dokumentasi cara buildnya akan sya tambahkan di 1 file.

Thanks :smile:

[bobbypriam]

Untuk manual ordering dia ada optionnya kok ditaruh di apidoc.json: http://apidocjs.com/#configuration-settings (ada key order)

Untuk yang ubah JS jadi Elixir ga priority sih. Cuma kalau bisa lebih bagus 🙂

Btw sebenernya apiDoc ini idealnya naro komennya inline di source codenya ya. Agak aneh ga sih kalau jadi file terpisah isinya comment aja? Kalau commentnya udah dalam bentuk comment Elixir, kita bisa pindahin dia ke atasnya function handler di tiap controller biar dokumentasi dan kode lebih deket. Ini untuk ke depannya aja sih, ga harus sekarang.

Kalau kita emang mau pakai ini, berarti ya lebih baik file RAML-nya hapus aja ya. Any thoughts @pyk @fajarmf?

[pyk]

fixed by #147 yah