Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- OpenMRS
- Teknik yazar:
- Saurabh
- Projenin adı:
- REST API İçin Kullanıcı Dostu GitHub Belgelerinin Kapsamını Genişletme
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Birincil Hedef
OpenMRS Swagger tabanlı REST API dokümanlarını, API'nin kullanımıyla ilgili yol gösterici bilgiler içerecek şekilde geliştirin.
Proje Açıklaması
OpenMRS REST API, geliştiricilerin OpenMRS'deki verilere erişmek için kullandığı temel mekanizmalardan biridir. OpenMRS Webservices API için otomatik olarak oluşturulmuş, Swagger tabanlı bir doküman ve GitHub tabanlı statik bir doküman da mevcut. GitHub tabanlı bu dokümanları Dokümanlar Sezonu'nda genişletmemiz gerekiyor.
KISA GENEL BAKIŞ
Burke'ün de belirttiği gibi OpenMRS Talk ile ilgili biraz araştırma yaptıktan sonra, bu projenin 2017'de bir GSOC projesi olarak başladığını öğrendim. Asıl hedefi OpenMRS REST API'sinin mevcut belgelerini iyileştirmek olan Gayan Weerakutti ile birlikte, Swagger Spesifikasyonunu iyileştirip Swagger Spesifikasyonu'nu oluşturma biçiminde iyileştirmeler yaparak promosyon dokümanlarının daha iyi bir sürümünü oluşturdu. Projede elde edilen ilgili tüm detaylar, bu OpenMRS konuşma gönderisinde özetlendi ve oldukça faydalı oldu.
Daha sonra 2019'da bu proje yenilendi ve bunun farklı versiyonlarını oluşturan Swagger dokümantasyon düzenlemelerine geçtik. Bunun yerine, bu Dokümanlar sezonunda kapsamını genişleteceğimiz statik GitHub uyumlu bir doküman geliştirdik.
Size anlatmak istediğim mevcut proje teklifinin özeti şöyle :
- Bazı popüler dillerde (özellikle Java ve JavaScript'ten bahsedildi) örnekler sunuyoruz.
- Swagger'ın "deneyin" özelliği gibi, seçenek listesi dokümanları için oyun alanı desteği eklendi.
- Şu ana kadar yapılan çalışmaların yeniden düzenlenmesi ve iyileştirilmesi.
- Eksik kaynakları bulup ekleme.
- Belgelerin konsol bölümüne biraz daha açıklama ekleme
AYRINTILI AÇIKLAMA
- Farklı dillerde örnekler verin.
Java'da SDK tabanlı olacak örnekler eklemenizi öneririm. Daha sonra dokümanlarımıza daha fazla derinlik katacağını düşündüğüm geriye dönük örnekler eklemenizi öneririm. Çünkü JavaScript gibi başka bir dilde örnekler eklemek, bu REST API'lerini OpenMRS Android İstemcisi üzerinde çalışırken kullandığım ve özellikle Android için uç noktaları kullanma konusunda yardıma ihtiyaç duyduğumda arayabileceğimiz herhangi bir kaynak yoktu. Android istemcisindeki OpenMRS API uç noktalarıyla karşılaştığım tecrübelerim göz önüne alındığında burada bazı kaliteli örnekler yapabileceğimi düşünebilirim. Bu konuyu mentorlarımla tartışacak ve verilen kararın üzerinde çalışacağım. Ayrıca, desteklenen işlemlere ilişkin örnekler eklemenin yanı sıra bazı programlama dillerinde OpenMRS sunucularıyla kimlik doğrulama örnekleri de eklemeliyiz. Şu anda bunun için yalnızca curl örneklerimiz var.
- Test API'leri örnekleri için Playground desteği ekleme
Bu özelliği demo sunucusunda barındırılan OpenMRS'nin promosyon belgelerinde kullandım. Tüm API belgelerinde bulunması gerçekten pratik bir araç. Burada biraz araştırma yaptım. Swagger-UI spesifikasyonunu mevcut statik dokümanlara yerleştirmek zor değil. Gizlemeyi göster/gizle açma/kapatma düğmelerini ve elimizdeki promosyon kodu belgesini kullanma. Bu şekilde, deneme özelliğinin geçerli API özellikleriyle kullanımda kalmasını bile sağlayabiliriz. Bu şekilde, oyun alanı özelliklerini mevcut statik belgelerimize entegre edebileceğimizi düşünüyorum.
- Şu ana kadar yapılan çalışmaların yeniden düzenlenmesi ve iyileştirilmesi
Mevcut curl örnekleri kontrol ediliyor
Bu bölüm, bu yıl projenin en önemli noktalarından biridir. Şu anda GitHub API dokümanlarında yalnızca curl örnekleri bulunmaktadır. Bunlardan bazıları, doğrudan tarayıcıdan kontrol etmek için demo sunucusunda doğrudan çalıştırılamaz. Tüm mevcut 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 yerine getirmek için swagger dokümanlarındaki yerleşik deneme özelliğine ek olarak Postman'ı kullanacağım.
Bazı örneklerde API yanıtları eksik
Mevcut curl örnekleri için bazı yanıtlar eklendi ancak bazı curl örneklerinde yanıt yok. Bence yanıtlar ayrıntılı olmasa bile (genellikle kaynağı temizlemek gibi işlemlerde durum söz konusuysa, olası tüm yanıt kodlarını ve bunları alma nedenini belgelemiş olsak da bunun için API belgelerindeki örnekleri daha tek tip hale getirmiş olsak da örnek bir JSON API Yanıtımız olmalı!)
Çeşitli işlemlerde eksik çalışan örnekler
Bence bu, daha önce tamamlanan çalışmayı API belgelerinde yeniden düzenlemenin en önemli kısmı olacak. Belgelerde cURL ile doğrudan yürütülebilecek somut örnekler var, ancak bunların bazıları biraz soyut özellikte olduğundan deneyimli geliştiricilere iyi bir referans vermekle birlikte yeni gelenleri rahatsız ediyor. OpenMRS konuşmasındaki bu gönderiden öğrendiğim gibi, iyi örneklerin paha biçilemez olduğu. Bu nedenle, söz dizimi vurgulamayı destekleyebiliriz. Bu, aslında pek işe yaramayan bir söz dizimini destekleyebilir. Bu yöntem, seçenek listesiyle birlikte geliyor, bu da burada öğrendiğim gibi, bunu oldukça kolay hale getiriyor.
Burke, gönderisinde iyi kullanıcı arayüzü ve parlak arayüz yerine dokümanlarda sadeliği ve açıklayıcılığı tercih ettiğini birçok kez vurguladığı için bu ilkelere bağlı kalır, şu anda OpenMRS Webservices API üzerinde çalışan geliştiricilerle konuşarak ve toplulukla etkileşime geçerek daha önce belirttiğim uç noktaları mümkün olduğunca açıklayıcı yapmaya çalışırım (örneğin, PR amaçlı kaynaklardaki özellik türleriyle ilgili açıklamaları toplamak için yaptığım gibi) Öncelikli konular üzerinde çalışıyor, mentorlarımla konuşarak ve dokümanlara gerçekten değer katan ve öncelikle tamamlanması gereken şeylerin hangileri olduğuna karar veriyorum.
Kullanım alanlarını açık başlık olarak ekleme
Konuyu anlamak için birçok API belgesi gördüm ve bunların hepsinin açık bir başlık olarak kullanım alanları olduğunu gördüm. Ancak açık bir şekilde görülemeyen kullanım durumlarımız var. Kaynakların ve alt kaynakların tanımlarından sonra gelen tanım ve örneklerde bir şekilde bir araya getirilmiş kullanım durumlarımız var.
Eksik kaynakları bulma ve belgeleme
Mevcut proje durumu için burada listelenen kaynaklar var, ancak burada promosyon dokümanlarının en son sürümünü gördüğümde, 2019 Sezonu'nda diğer kaynaklardaki açıklamalarıyla birlikte GitHub'a uygun API dokümanlarındaki mevcut kaynak paketine eklenebilecek birçok kaynak buldum. Dokümanlara eklenmesi gereken konuları tartışıp uygun bir şekilde ekleyeceğim.
SONUÇ
Bir süredir OpenMRS topluluğunun bir parçasıyım. Sunucularla etkileşimde bulunmak için API'lerle sıklıkla etkileşimde bulunduğum Android İstemci projesine aktif olarak katkıda bulunuyorum. Bu nedenle, bu API belgelerini genişletme projesi üzerinde çalışabileceğimi düşünüyorum çünkü bir geliştirici olarak kendi çalışmamı görüntüleyebilir ve diğer geliştiricilerin çalışmalarını gerçekten kolaylaştırıp kolaylaştırmadığını değerlendirebilirim.Burada barındırılan kullanıcı dostu belge deposu için kullanılan araçları öğrendim, bu depoya da çeşitli katkılar sağladım. Bu şekilde API belgelerinin daha iyi bir API'si olduğunu düşünüyorum.
İlerleme durumu hakkında her hafta bir konuşma gönderilerek topluluktan geri bildirim almaya yardımcı olacağım. Bu belgeleme döneminden en iyi şekilde faydalanmak için mentorum ve topluluğumla yakından ilişki içinde çalışacak şekilde çalışacağım.