OpenMRS projesi

Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.

Proje özeti

Açık kaynak kuruluşu:
OpenMRS
Teknik yazar:
Saurabh
Proje adı:
REST API için Kullanıcı Dostu GitHub Belgelerini Genişletme
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

Birincil Hedef

API'nin kullanımıyla ilgili yönergeler eklemek için OpenMRS Swagger tabanlı REST API belgelerini iyileştirin.

Proje açıklaması

OpenMRS REST API, geliştiricilerin OpenMRS'deki verilere erişmesi için temel mekanizmalardan biridir. OpenMRS Webservices API'nin Swagger tabanlı otomatik olarak oluşturulmuş bir dokümanı ve statik GitHub tabanlı bir dokümanı zaten mevcut. Bu Dokümanlar Sezonu'nda GitHub tabanlı dokümanı genişletmemiz gerekiyor.

KISA GENEL BAKIŞ

Burke'nin önerdiği gibi OpenMRS Talk hakkında biraz araştırma yaptıktan sonra bu projenin 2017'de GSOC projesi olarak başladığını öğrendim. Gayan Weerakutti ile birlikte, Swagger spesifikasyonunu iyileştirerek ve Swagger spesifikasyonunun oluşturulma biçiminde iyileştirmeler yaparak OpenMRS REST API'nin mevcut dokümantasyonunu iyileştirmeyi amaçladık. Böylece Swagger dokümantasyonunun daha iyi bir sürümü oluşturuldu. Projede elde edilen tüm ilgili ayrıntılar bu OpenMRS sohbet yayınında özetlendi ve oldukça faydalı oldu.

Daha sonra, 2019'da bu proje yenilendi ve Swagger dokümantasyonunda bu konuda varyasyonlar oluşturan ince ayarlarla devam ettik. Bunun yerine, Dokümanlar'ın bu sezonunda genişleteceğimiz, GitHub'a uygun statik bir doküman geliştirdik.

Açıklamak istediğim mevcut proje teklifinin kısa bir özeti şu şekildedir :

  1. Bazı popüler dillerden (özellikle Java ve JavaScript'ten bahsedilmiş) örnekler geliyor.
  2. Swagger ""deneme"" özelliğinde olduğu gibi seçenek listesi belgeleri için oyun alanı desteği ekleme.
  3. Şimdiye kadar yapılan çalışmaları yeniden düzenleme ve iyileştirme.
  4. Eksik kaynakları bulup ekleme.
  5. Dokümanların konsol bölümüne biraz daha açıklama ekleme

AYRINTILI AÇIKLAMA

  1. Farklı dillerde örnekler verin.

Java'da SDK tabanlı örnekler eklemenizi ve ardından dokümanlarımıza daha fazla derinlik katmak için geriye dönük örnekler eklemenizi öneririm. Bunun nedeni, JavaScript gibi bir dilde örnekler eklemek, geriye dönük örnekler eklemekten çok işe yaramaz. OpenMRS Android istemcisinde çalışırken bu REST API'leri kullandığım ve özellikle Android için uç noktaları kullanma konusunda yardıma ihtiyaç duyduğumda başvurabileceğim bir kaynak olmadığını düşünüyorum. Android istemcisinde OpenMRS API uç noktalarıyla uğraştığım deneyimlerime dayanarak burada gerçekten kaliteli örnekler verebilirim. Bu konuyu danışmanlarımla görüşecek ve karara varılan konuyla ilgili çalışacağım. Ayrıca, desteklenen işlemler için örnekler eklemenin yanı sıra bazı programlama dillerinde OpenMRS sunucularıyla kimlik doğrulama örnekleri de eklememiz gerekiyor. Şu anda bunun için yalnızca curl örneklerimiz vardır.

  1. API örneklerini test etmek için Playground desteği ekleme

Bu özelliği, demo sunucusunda barındırılan OpenMRS'nin swagger dokümanında kullandım. Herhangi bir API dokümanında bulunması gerçekten kullanışlı bir araçtır. Burada biraz araştırma yaptım. Swagger-UI spesifikasyonunu mevcut statik belgelere yerleştirmek o kadar zor değil. Göster/gizle açma/kapatma düğmelerini ve mevcut swagger doküman kodunu kullanarak. Bu sayede deneme özelliğinin mevcut API spesifikasyonlarıyla etkin kalmasını sağlayabiliriz. Bu şekilde, oyun alanı özelliklerini mevcut statik dokümanlarımıza entegre edebileceğimize inanıyorum.

  1. Şimdiye kadar yapılan çalışmaları yeniden düzenleme ve iyileştirme
Mevcut curl örneklerini kontrol etme

Bu bölüm, bu yılki projenin ana odaklarından biridir. Şu anda GitHub API dokümanlarında yalnızca curl örnekleri bulunmaktadır. Bunların bazıları, doğrudan tarayıcıdan kontrol etmek için doğrudan demo sunucusunda çalıştırılamaz. Mevcut tüm uç noktaları test edeceğim ve bu curl isteklerini çalıştırırken aldığımız çeşitli curl örneklerinin yanıtlarını içeren basit bir belge tutacağım. Gerekirse bu görevi tamamlamak için Postman'ı ve swagger dokümanlarında bulunan yerleşik deneme özelliğini kullanacağım.

Bazı örneklerde API yanıtları eksik

Mevcut curl örnekleri için bazı yanıtlar eklenmiştir ancak curl örneklerinin bazılarında yanıt yoktur. Yanıtlar ayrıntılı olmasa bile (genellikle kaynağı temizleme gibi işlemlerde olduğu gibi), olası tüm yanıt kodlarını ve bunları alma nedenimizi belgelemiş olsak da örnek bir JSON API yanıtına sahip olmalıyız. Bu, API belgelerindeki örneklerin daha tek tip olmasını sağlayacağını düşünüyorum!

Çeşitli işlemlerle ilgili çalışan örnekler eksik

API dokümanlarında daha önce tamamlanan çalışmaları yeniden düzenlemenin en önemli kısmının bu olacağını düşünüyorum. Dokümanda doğrudan cURL ile yürütülebilecek somut örnekler var ancak bunların bazıları biraz soyut. Bu durum, deneyimli geliştiricilere iyi bir referans sağlarken yeni gelenleri endişelendiriyor. OpenMRS konuşmasındaki bu yazıdan öğrendiğim gibi iyi örnekler paha biçilmezdir. Bu nedenle, iş örnekleri eklemenin yanı sıra söz dizimi vurgulamayı da destekleyebiliriz. Bu özellik pek de pek zor bir iş değil. Bu, burada öğrendiğim gibi, bunu yapmayı oldukça kolay hale getiriyor.

Burke, yayınında iyi bir kullanıcı arayüzü ve parlak arayüz yerine dokümanlarda basitliği ve açıklayıcılığı tercih ettiğini birçok kez vurgulamıştı. Bu ilkelere bağlı kalarak, şu anda OpenMRS Webservices API'de çalışan geliştiricilerle konuşarak ve toplulukla etkileşim kurarak önceden belgelenen uç noktaları mümkün olduğunca açıklayıcı hale getirmeye çalışacağım. Tıpkı buradaki form kaynakları için özellik türlerini net bir şekilde toplamak için yaptığım gibi. Öncelikli olarak, danışmanlarımla görüşerek ve belgelere gerçekten değer katan ve öncelikli olarak yapılması gereken konuları belirleyerek çalışırım.

Kullanım alanlarını açık bir başlık olarak ekleme

API'leri anlamak için birçok API dokümanı inceledim ve bunların hepsinin açık bir başlık olarak kullanım alanlarına sahip olduğunu gördüm. Ancak, açıkça görünmeyen kullanım alanlarımız var. Bunlar, kaynaklar ve alt kaynakların tanımlarından sonra gelen tanım ve örneklerin içine biraz yerleştirilmiş durumda. Geliştiricilerin kullanım alanlarını anlamak için tanımlarda arama yapması gerekmemesi ve doğrudan bu alanlara bakabilmesi için kullanım alanlarını dokümanda ayrı bir öğe olarak ayırmamız gerektiğini düşünüyorum.

  1. Eksik kaynakları bulma ve belgeleme

    Mevcut proje durumunda burada kaynaklar listelenmiştir ancak buradaki swagger dokümanının en son sürümünü gördüğümde, GitHub'a uygun API dokümanlarındaki mevcut kaynak grubuna eklenebilecek birçok kaynağı, dokümanlar sezonu 2019 sırasında diğer kaynaklarla birlikte tamamlanan açıklamayla birlikte belirleyebildim. Dokümanlara eklenmesi gereken konuları tartışıp uygun şekilde ekleyeceğim.

SONUÇ

Bir süredir OpenMRS topluluğunun bir parçasıyım. Android istemci projesinde aktif bir katkıda bulunanım. Sunucularla etkileşim kurmak için sık sık API'lerle etkileşim kuruyorum. Bu nedenle, API dokümanlarını genişletme projesi üzerinde oldukça iyi çalışabileceğimi düşünüyorum. Çünkü kendi çalışmamı bir geliştirici olarak görebilir ve diğer geliştiricilerin işini gerçekten kolaylaştırıp kolaylaştırmadığını değerlendirebilirim. Burada barındırılan kullanıcı dostu doküman deposu için kullanılan araçlarla tanıştım. Depoya ve araçlara (ör. slateUI) aşina olmak için bu depoya da çeşitli katkılarda bulundum. Bir API'nin dokümanlarıyla aynı derecede iyi olduğu düşünüldüğünden, dokümanlarını iyileştirerek OpenMRS Rest API'lerini biraz daha iyi hale getirmek isterim.

Topluluktan geri bildirim almamıza yardımcı olacak bir konuşma gönderisi ile ilerleme durumunu haftalık olarak paylaşacağım. Ayrıca, bu dokümantasyon döneminden en iyi şekilde yararlanmak için mentorum ve topluluğumla yakın bir şekilde çalışacağım.