Project OpenMRS

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

Ringkasan proyek

Organisasi open source:
OpenMRS
Penulis teknis:
Saurab
Nama proyek:
Memperluas Dokumentasi GitHub yang Mudah Digunakan untuk REST API
Durasi proyek:
Durasi standar (3 bulan)

Project description

Tujuan Utama

Tingkatkan kualitas dokumentasi REST API berbasis OpenMRS Swagger 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 berbasis Swagger yang dibuat secara otomatis dan juga dokumentasi berbasis GitHub statis, kita seharusnya memperluas dokumentasi berbasis GitHub tersebut di Season Dokumen ini.

RINGKASAN SINGKAT

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

Lalu, pada tahun 2019, proyek ini diubah, dan kami beralih dari dokumentasi Swagger yang mengubah-ubahnya menghasilkan variasi. Sebagai gantinya, kami mengembangkan dokumentasi ramah GitHub statis yang akan diperluas dalam musim Dokumen ini.

Jadi singkat dari proposal proyek saat ini yang ingin saya jelaskan adalah :

  1. Memberikan contoh dalam beberapa bahasa populer (khususnya yang menyebutkan java dan javascript).
  2. Menambahkan dukungan playground untuk dokumentasi slate seperti fitur ""try-out"" Swagger.
  3. Memfaktorkan ulang dan meningkatkan pekerjaan yang telah diselesaikan hingga saat ini.
  4. Mencari dan menambahkan resource yang hilang.
  5. Menambahkan lebih banyak deskripsi ke bagian konsol pada dokumen

DESKRIPSI DETAIL

  1. Menghasilkan contoh dalam berbagai bahasa.

Saya sarankan menambahkan contoh di java yang akan berbasis SDK lalu menambahkan contoh retrofit yang menurut saya akan menambah lebih dalam dokumentasi kami, karena menambahkan contoh dalam satu bahasa lagi seperti JavaScript tidak akan banyak membantu sebagai menambahkan contoh retrofit karena saya telah menggunakan REST API ini saat mengerjakan OpenMRS Android Client, dan tidak ada sumber daya untuk dicari setiap kali saya membutuhkan bantuan menggunakan endpoint khusus untuk android. Dan saya benar-benar dapat membuat beberapa contoh berkualitas di sini mengingat pengalaman saya mengutak-atik endpoint OpenMRS API di klien Android. Saya akan mendiskusikan ini dengan mentor saya dan mengerjakan apa yang diputuskan. Selain itu, selain menambahkan contoh untuk operasi yang didukung, kita juga perlu 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 fitur ini sangat mudah dimiliki dalam dokumentasi API. Saya meneliti sedikit 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 terbaru yang kami 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 dapat mengintegrasikan fitur playground ke dalam dokumentasi statis kami saat ini.

  1. Memfaktorkan ulang dan meningkatkan pekerjaan yang telah diselesaikan 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 yang sebagian tidak dapat dijalankan langsung di server demo untuk diperiksa langsung dari browser. Saya akan menguji semua endpoint saat ini dan mempertahankan dokumen sederhana dengan berbagai respons contoh curl yang kita dapatkan saat menjalankan permintaan curl tersebut. Saya akan menggunakan Postman sebagai tambahan 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 pikir meskipun responsnya tidak panjang yang biasanya terjadi dengan operasi seperti membersihkan resource, kita akan memiliki contoh Respons API JSON meskipun kita telah mendokumentasikan semua kode respons yang mungkin dan alasannya, saya pikir ini akan membuat contoh di seluruh dokumentasi API lebih seragam.

Kehilangan contoh kerja di berbagai operasi

Saya pikir ini akan menjadi bagian terpenting dari pemfaktoran ulang pekerjaan yang telah diselesaikan sebelumnya dalam dokumentasi API. Ada contoh konkret dalam dokumentasi yang dapat langsung dieksekusi dengan cURL, tetapi beberapa di antaranya sedikit abstrak yang memberikan referensi yang baik untuk developer berpengalaman tetapi membuat para pendatang baru merasa repot. Seperti yang bisa saya kumpulkan dari postingan ini di OpenMRS berbicara bahwa contoh yang baik sangat berharga, jadi selain menambahkan contoh pekerjaan, kami dapat mendukung penyorotan sintaksis yang memang tidak banyak pekerjaannya yang dibundel dengan slate yang membuatnya cukup mudah dilakukan seperti yang saya temukan di sini,

Seperti yang telah ditekankan oleh burke berkali-kali dalam postingannya, dengan lebih memilih kesederhanaan dan deskriptif dalam dokumen daripada UI yang bagus dan antarmuka yang menarik, saya akan mematuhi prinsip-prinsip ini dan mencoba membuat endpoint yang didokumentasikan sebelumnya sejelas mungkin dengan berbicara kepada developer yang saat ini mengerjakan OpenMRS Webservices API dan berinteraksi dengan komunitas, seperti yang saya lakukan di postingan bincang-bincang untuk mengumpulkan deskripsi jenis atribut untuk referensi formulir yang tidak jelas bagi saya di sini. Saya akan benar-benar mengerjakan hal-hal yang diprioritaskan dengan bijak, berbicara dengan mentor saya, dan memutuskan hal-hal yang benar-benar memberi nilai tambah untuk dokumen dan harus diselesaikan terlebih dahulu.

Menambahkan Kasus penggunaan sebagai judul eksplisit

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

  1. Menemukan dan mendokumentasikan referensi yang hilang

    Status proyek saat ini memiliki sumber daya yang tercantum di sini, tetapi setelah melihat versi terbaru dokumentasi swagger di sini, saya bisa menemukan banyak sumber daya yang dapat ditambahkan ke rangkaian sumber daya saat ini di dokumen API yang ramah GitHub dengan deskripsi seperti yang dicapai dengan sumber daya lain selama Musim Dokumen 2019. Saya akan membahas topik yang perlu ditambahkan ke dokumen dan menambahkannya sesuai kebutuhan.

KESIMPULAN

Saya sudah cukup lama menjadi bagian dari komunitas OpenMRS. Saya adalah kontributor aktif pada project Klien Android, tempat saya sering berinteraksi dengan API untuk berinteraksi dengan server. Oleh karena itu, saya merasa dapat mengerjakan proyek ini untuk memperluas dokumen API dengan cukup baik karena saya sendiri dapat melihat pekerjaan saya sebagai developer dan mengevaluasi apakah itu benar-benar memudahkan pekerjaan developer lain atau tidak, saya sudah terbiasa dengan alat yang digunakan untuk repositori dokumentasi yang mudah digunakan dan dihosting di sini, saya juga telah memberikan beberapa kontribusi pada repo ini untuk membiasakan diri dengan repositori ini dan alatnya adalah slateUI yang lebih baik.

Saya akan memastikan untuk mengomunikasikan progres setiap minggu melalui postingan bincang-bincang yang akan membantu mendapatkan masukan dari komunitas dan bekerja sama dengan mentor dan komunitas saya untuk mendapatkan hasil terbaik dari periode dokumentasi ini.