[rojak-api] New UI for API Documentation

[reinarduswindy]

Pembuatan dokumentasi API saya menggunakan apiDoc. Karena apiDoc jenisnya komen inline, maka sya taruh di handler masing-masing controller, sesuai yang dikatakan oleh mas @bobbypriambodo di #133 .

Hasil dari UI barunya bisa dilihat di sini https://rawgit.com/reinarduswindy/rojak/master/rojak-api/spec/index.html.

Mohon review dan pendapat lainnya. Thanks 😄

[pyk]

Cc @bobbypriambodo

[bobbypriam]

Thanks for this @reinarduswindy. Tapi diffnya cukup besar juga ya, kayaknya agak ga efisien kalo reviewnya langsung jump in ke diff.

Boleh kasih overview file-file/direktori apa saja yang berubah/ditambahkan/dikurangi? Mana yang digenerate (+ gimana cara generatenya) dan mana yang perlu kita maintain sendiri? Terus direktori locales dan vendor isinya banyak juga ya, itu emang dibutuhkan semua?

Takutnya technical debt dan jadi ga maintainable nih 😅

[reinarduswindy]

Iya mas @bobbypriambodo .

1. File-file yang berubah ada di masing-masing controller, jdi akhirnya sya buat komen apidoc di atas masing-masing handler controller (candidate_controller, media_controller, news_controller, pairing_controller).
2. Semua file yang berkaitan dengan RAML dihapus semua, termasuk spec-api.html (digantikan dengan index.html).
3. File yang ditambahkan ada apidoc.json dan package.json, file ini inisialisasi awal untuk generate file-file apidoc. Semua file yang ada di /spec/ adalah hasil generate dari apidoc itu sendiri.

Untuk cara generatenya sya lupa buat filenya 😅 . Generate apidoc di sini tinggal jalankan apidoc -i web/v1 -o spec/ di terminal dari path /rojak-api/ (pastikan sudah install apidoc). -i web/v1 untuk ambil input dari direktori web/v1 dan o spec/ untuk output hasil ke direktori spec/. Hasil output UI nya bisa dilihat dari spec/index.html.

Direktori locales dan vendor isinya file-file yang jadi support (javascript dan css) ke index.html, jadi gak bisa dihilangkan.

[bobbypriam]

I see, berarti yang ada di spec/ itu build artifact semua ya, dan file yang dibutuhkan untuk generate docnya adalah apidoc.json, package.json, dan comment @apidoc di controller.

Overall sudah oke sih harusnya, tapi saya mau request beberapa change:

1. package.json kalau bisa distrip jadi field yang diperlukan aja. Kita di sini kan bukan project Node.js, jadi field kayak author, test, repo, issues, dsb kalo bisa dihapus mending ga usah ada :sweat_smile: grunt-apidoc di devDependencies juga dipake ga ya?
2. Saya baru lihat dari HP (lagi di luar), tapi saya notice ada beberapa indent yang ga konsisten lebarnya (ada 2, ada 4) di file controller dan apidoc.json. Kalau bisa dibuat konsisten aja mas pakai 2 space (jangan tab ya).
3. Bisa ga ya kita tambahin readme di spec/ untuk ngasih tau bahwa isi direktorinya autogenerated dan kita jangan ngubah in place?
4. Dokumentasi generate API-nya taro di readme.md rojak-api aja mas biar ga kebanyakan file. Kalo bisa kasih link ke apidocnya juga kalo ada yang mau install :smile:

Thanks!

[reinarduswindy]

@bobbypriambodo ternyata package.json tidak diinclude juga bisa. Nanti akan sya hapus. 😅

[pyk]

@reinarduswindy btw ini untuk api-spec.html aja kan? kok banyak banget ya files di PR nya, ada ~80files lebih

[reinarduswindy]

@pyk Iya, files nya hasil dari generate apidoc itu sendiri sih. Emg banyak files kecilnya gitu terutama di vendor dan locales.

[pyk]

@reinarduswindy hooo jadi itu output dari apidocs ya.

Maaf maaf baru baca-baca tentang apidocs disini http://apidocjs.com/

Jadi sebenarnya yang penting itu apidoc.json sama inline comment di *.ex kan? misalnya seperti rojak-api/web/v1/candidate/candidate_controller.ex. Kalo gitu itu aja yang dicommit, toh yang lain kita bisa generate lagi (btw karena gak ada gunanya juga kita track version nya)

[reinarduswindy]

@pyk nahhh tadinya mau gitu, tpi masalahnya vendor dan locale itu berisi files js dan css yang diinclude kan ke dalam index.html nya.

[pyk]

@reinarduswindy hoo I see mas, gak apa mas toh bisa generate lagi kan sama apidoc

[bobbypriam]

Iya tadi saya juga agak ragu mau approve ngeliat changenya cukup banyak.. saya juga setuju sama @pyk cukup apidoc.json dan comment di controller aja yang masuk ke git supaya reponya lebih simple. Mungkin kita hapus spec/ dari index git dan tambahkan ke .gitignore?

Berarti kita harus ada otomasi ngebuild docsnya ya untuk ditaro di server. Agak cringe juga sih ngeliat output dari apiDoc bloated banget 😅

[pyk]

Berarti kita harus ada otomasi ngebuild docsnya ya untuk ditaro di server.

Untuk sekarang manual aja juga boleh mas, yang penting step2 nya di tulis. Mungkin install apidoc terus command yg di pakai untuk generate gitu

[reinarduswindy]

@pyk @bobbypriambodo agak kurang paham sih dengan maksudnya. 😅 yang aku tangkap, jadi direktori spec/ nya dihapus dulu?

[bobbypriam]

@reinarduswindy Iya, intinya yang di-commit di repo hanya comment @apidoc dan file apidoc.json-nya aja, plus cara generate dokumentasi dari file-file itu. Minimum changes yang perlu.

Untuk hasil ngebuildnya kita ga perlu masukin repo. Nanti kan kita akan taro file-file html dll itu ke server, jadinya step build dan upload (either via ftp, scp, dan sebagainya) bisa dilakukan di mesin local masing-masing atau via CI dan bisa guaranteed hasilnya akan sama. Mau build langsung di server juga bisa.

Jadi iya, saya kira direktori spec/ dihapus aja pakai git rm.

[reinarduswindy]

hooo, oke mas @bobbypriambodo

[pyk]

LGTM 👌

[bobbypriam]

Wait mas, kayaknya ada specnya yang salah

[bobbypriam]

Iya, baru keliatan pas diffnya ga terlalu banyak.

Untuk resource yang cuma satu (Get a candidate, get a media, dll) itu responsenya harusnya langsung object, bukan array. Untuk 404 juga errornya langsung object, bukan array. Itu kok ada []-nya ya?

[bobbypriam]

Thanks @reinarduswindy, saya mau coba generate di lokal saya dulu ya.

[reinarduswindy]

Iya, sama" mas @bobbypriambodo . Thanks juga buat mas @bobbypriambodo dan @pyk yang sudah mau membantu. 😄

[bobbypriam]

Siap, sudah berhasil (cepet juga ya generatenya, ga ada satu detik). Ada beberapa concern terhadap copywriting dari dokumentasinya sih tapi kayaknya udah di luar scope PR ini, dan UI-nya sendiri yang jadi fokus PR ini udah bagus.

Maaf banget nih mas, boleh minta change sedikit lagi? :smile: Comment @apidoc taronya di atasnya defparams dari masing-masing handler, biar ngedeketin defparams dari suatu handler ke handlernya. Jadi urutannya: @apidoc, defparams, def index.

Other than that, LGTM 👍 @pyk kayaknya udah bisa dimerge abis change yang ini.

[reinarduswindy]

oke mas @bobbypriambodo . langsung saya ganti skrg.. 😄

[pyk]

udah up! http://api.rojak.id/ 🙇

[reinarduswindy]

Thanks mas @pyk 😄