Project OpenMRS

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.

Ringkasan project

Organisasi open source:
OpenMRS
{i>Technical writer <i}(Penulis teknis):
Saurabh
Nama project:
Memperluas Dokumentasi GitHub yang Mudah Digunakan untuk REST API
Durasi project:
Durasi standar (3 bulan)

Project description

Tujuan Utama

Meningkatkan dokumentasi REST API berbasis Swagger OpenMRS untuk menambahkan panduan tentang penggunaan API.

Deskripsi Project

OpenMRS REST API adalah salah satu mekanisme utama bagi developer untuk mengakses data dari OpenMRS. Sudah ada dokumentasi OpenMRS Webservices API yang dibuat otomatis berbasis Swagger dan dokumentasi statis berbasis GitHub juga, kita seharusnya memperluas dokumentasi berbasis GitHub tersebut dalam Season of Docs ini.

RINGKASAN SINGKAT

Setelah melakukan sedikit riset tentang OpenMRS Talk seperti yang disarankan Burke, saya mengetahui bahwa project ini dimulai pada tahun 2017 sebagai project GSOC. Dengan Gayan Weerakutti, tujuan utamanya adalah meningkatkan dokumentasi OpenMRS REST API yang ada, dengan meningkatkan Spesifikasi Swagger-nya dan melalui peningkatan cara Spesifikasi Swagger-nya dibuat sehingga versi dokumentasi swagger yang lebih baik dihasilkan. Semua detail relevan yang dicapai dalam proyek diringkas di sini dalam postingan pembahasan OpenMRS ini dan sangat berguna.

Kemudian, pada tahun 2019, project ini diubah, dan kami beralih dari tweak dokumentasi Swagger yang menghasilkan variasi pada hal ini. Sebagai gantinya, kami mengembangkan dokumentasi statis yang kompatibel dengan GitHub yang akan kami perluas dalam musim Dokumen ini.

Jadi, ringkasan proposal project saat ini yang ingin saya jelaskan adalah :

  1. Menemukan contoh dalam beberapa bahasa populer (khususnya java dan javascript).
  2. Menambahkan dukungan playground untuk dokumentasi slate seperti fitur ""coba"" Swagger.
  3. Memfaktorkan ulang dan meningkatkan pekerjaan yang dilakukan hingga saat ini.
  4. Menemukan dan menambahkan resource yang tidak ada.
  5. Menambahkan deskripsi selengkapnya ke bagian konsol dalam dokumen

DESKRIPSI DETAIL

  1. Buat contoh dalam berbagai bahasa.

Saya akan menyarankan untuk menambahkan contoh dalam java yang akan berbasis SDK, lalu menambahkan contoh retrofit yang menurut saya akan menambah kedalaman dokumentasi kita, karena menambahkan contoh dalam satu bahasa lagi seperti JavaScript tidak akan banyak membantu seperti menambahkan contoh retrofit karena saya telah menggunakan REST API ini saat mengerjakan OpenMRS Android Client, dan tidak ada referensi yang dapat dicari setiap kali saya memerlukan bantuan untuk menggunakan endpoint khusus untuk Android. Dan saya akan dapat membuat beberapa contoh berkualitas di sini dengan serius mengingat pengalaman saya dalam menggunakan endpoint OpenMRS API di klien Android. Saya akan mendiskusikannya dengan mentor saya dan mengerjakan apa yang diputuskan. Selain menambahkan contoh untuk operasi yang didukung, kita juga harus menambahkan contoh untuk mengautentikasi dengan server OpenMRS dalam beberapa bahasa pemrograman. Saat ini kami hanya memiliki contoh curl untuk ini.

  1. Menambahkan dukungan Playground untuk contoh API pengujian

Saya telah menggunakan fitur ini dalam dokumentasi swagger OpenMRS yang dihosting di server demo, dan ini adalah alat yang sangat praktis untuk dimiliki dalam dokumentasi API apa pun. Saya telah melakukan sedikit riset di sini, dan tidak terlalu sulit untuk menyematkan spesifikasi Swagger-UI ke dalam dokumentasi statis saat ini. Menggunakan tombol tampilkan sembunyikan dan menggunakan kode dokumentasi swagger saat ini yang kita miliki. Dengan cara ini, kita bahkan dapat memastikan bahwa fitur uji coba tetap aktif dengan spesifikasi API saat ini. Ini adalah salah satu cara yang saya yakini kita dapat mengintegrasikan fitur playground ke dalam dokumentasi statis saat ini.

  1. Memfaktorkan ulang dan meningkatkan pekerjaan yang dilakukan hingga saat ini
Memeriksa contoh curl saat ini

Bagian ini adalah salah satu penekanan utama project ini tahun ini. Saat ini, hanya contoh curl yang ada di dokumen GitHub API, beberapa di antaranya tidak dapat langsung dijalankan di server demo untuk memeriksa langsung dari browser. Saya akan menguji semua endpoint saat ini dan mengelola dokumen sederhana dengan berbagai respons contoh curl yang kita dapatkan saat menjalankan permintaan curl tersebut. Saya akan menggunakan Postman selain fitur uji coba bawaan dalam dokumentasi swagger untuk menyelesaikan tugas ini jika diperlukan.

Respons API tidak ada di beberapa contoh

Beberapa respons telah ditambahkan untuk contoh curl saat ini, tetapi beberapa contoh curl tidak memiliki respons. Saya rasa meskipun respons tidak panjang, yang biasanya terjadi pada operasi seperti menghapus resource, kita harus memiliki contoh Respons JSON API meskipun kita telah mendokumentasikan semua kemungkinan kode respons dan alasan untuk mendapatkannya. Saya rasa ini akan membuat contoh di seluruh dokumentasi API lebih seragam.

Contoh yang berfungsi di berbagai operasi tidak ada

Saya rasa ini akan menjadi bagian terpenting dari pemfaktoran ulang pekerjaan yang telah dilakukan sebelumnya dalam dokumentasi API. Ada contoh konkret dalam dokumentasi yang dapat langsung dieksekusi dengan cURL, tetapi beberapa di antaranya agak abstrak yang memberikan referensi yang baik bagi developer berpengalaman, tetapi membuat pendatang baru merasa terganggu. Seperti yang dapat saya kumpulkan dari postingan ini dalam diskusi OpenMRS bahwa contoh yang baik tidak ternilai harganya, jadi selain menambahkan contoh pekerjaan, kita dapat mendukung sorotan sintaksis yang memang tidak banyak pekerjaan, tetapi hampir dipaketkan dengan slate yang membuat ini cukup mudah dilakukan seperti yang saya temukan di sini,

Seperti yang ditekankan oleh burke berkali-kali dalam postingannya, mereka lebih menyukai kesederhanaan dan deskripsi dalam dokumen sebagai pengganti UI yang bagus dan antarmuka yang menarik, saya akan mematuhi prinsip-prinsip ini dan mencoba membuat endpoint yang telah didokumentasikan sejelas mungkin dengan berbicara kepada developer yang sedang mengerjakan OpenMRS Webservices API dan berinteraksi dengan komunitas, seperti yang saya lakukan di postingan bincang-bincang untuk mengumpulkan deskripsi jenis atribut untuk resource formulir yang tidak jelas bagi saya dalam referensi formulir di sini. Saya akan benar-benar mengerjakan hal-hal yang diprioritaskan, berbicara dengan mentor saya, dan memutuskan hal-hal yang benar-benar menambah nilai pada dokumen dan perlu diselesaikan terlebih dahulu.

Menambahkan Kasus penggunaan sebagai judul eksplisit

Saya telah melihat banyak dokumentasi API untuk memahaminya dan melihat bahwa semuanya memiliki kasus penggunaan sebagai judul eksplisit, meskipun kita memiliki kasus penggunaan yang tidak terlihat secara eksplisit, mereka agak menyatu di dalam definisi dan contoh yang mengikuti setelah definisi resource dan subresource. Saya rasa kita harus berupaya memisahkan Kasus Penggunaan sebagai entitas terpisah dalam dokumentasi sehingga kasus penggunaan developer tidak benar-benar harus mencari tahu definisinya.

  1. Menemukan dan mendokumentasikan sumber daya yang hilang

    Status project saat ini memiliki resource yang tercantum di sini, tetapi setelah melihat dokumentasi swagger versi terbaru di sini, saya dapat menemukan banyak resource yang dapat ditambahkan ke rangkaian resource saat ini dalam dokumen API yang mudah digunakan GitHub dengan deskripsi seperti yang dilakukan dengan resource lain selama Season of Docs 2019. Saya akan membahas topik yang perlu ditambahkan ke dokumen dan menambahkannya dengan sesuai.

KESIMPULAN

Selama beberapa waktu, saya telah menjadi bagian dari komunitas OpenMRS. Saya adalah kontributor aktif untuk project Klien Android tempat saya sering berinteraksi dengan API untuk berinteraksi dengan server. Oleh karena itu, saya merasa dapat mengerjakan project ini untuk memperluas dokumen API dengan cukup baik karena saya dapat melihat pekerjaan saya sebagai developer dan mengevaluasi apakah hal itu benar-benar memudahkan pekerjaan developer lain atau tidak. Saya telah memahami alat yang digunakan untuk repositori dokumentasi yang mudah digunakan yang dihosting di sini. Saya juga telah memberikan beberapa kontribusi ke repo ini untuk memahami repositori dan alat, yaitu slateUI. Karena API dianggap sama bagusnya dengan dokumentasinya, saya ingin membuat OpenMRS Rest API sedikit lebih baik dengan meningkatkan dokumentasinya.

Saya akan memastikan untuk menyampaikan progres setiap minggu dengan postingan diskusi yang akan membantu mendapatkan masukan dari komunitas dan bekerja sama erat dengan mentor dan komunitas saya untuk mendapatkan hasil terbaik dari periode dokumentasi ini.