Bu sayfa, Google Dokümanlar Sezonu için kabul edilen teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- OpenMRS
- Teknik yazar:
- Saurabh
- Proje 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 kılavuz ekleyerek iyileştirin.
Proje Açıklaması
OpenMRS REST API, geliştiricilerin OpenMRS'deki verilere erişmesi için kullanılan temel mekanizmalardan biridir. OpenMRS Webservices API için otomatik olarak oluşturulmuş, Swagger tabanlı bir doküman ve ayrıca statik GitHub tabanlı bir doküman da mevcut.
KISA GENEL BAKIŞ
Burke'ün de belirttiği gibi, OpenMRS Talk'ta yaptığım araştırmaların ardından bu projenin 2017'de bir GSOC projesi olarak başladığını öğrendim. Gayan Weerakutti'de ana hedef; Swagger Spesifikasyonu'nu iyileştirerek ve Swagger Spesifikasyonu'nun oluşturulma biçiminde iyileştirmeler yaparak swagger dokümanlarının daha iyi bir sürümünün oluşturulması yoluyla OpenMRS REST API'sinin mevcut belgelerini iyileştirmek olan Gayan Weerakutti ile. Projede ulaşılan ilgili tüm detaylar bu OpenMRS konuşma gönderisinde özetlendi ve oldukça yararlı oldu.
Daha sonra 2019'da bu proje yenilendi ve bunun farklı versiyonları olan Swagger dokümantasyonundaki ince ayara geçiş yaptık. Bunun yerine, bu Dokümanlar sezonunda genişleteceğimiz statik GitHub dostu bir doküman geliştirdik.
Açıklamak istediğim mevcut proje teklifinin özeti şöyle :
- Bazı popüler dillerde (özellikle java ve JavaScript'ten bahsedildi) örnekler sunulacak.
- Swagger ""deneyin"" özelliğinde olduğu gibi seçenek listesi belgeleri için oyun alanı desteği eklendi.
- Şu ana kadar yapılan çalışmaların yeniden düzenlenmesi ve iyileştirilmesi.
- Eksik kaynakları bulma ve ekleme.
- Belgelerin konsol bölümüne biraz daha fazla açıklama ekleme
AYRINTILI AÇIKLAMA
- Farklı dillerde örnekler verebilir.
Java'da SDK tabanlı örnekler eklemenizi öneririm. Sonra da dokümanlarımıza daha fazla derinlik katacağını düşünüyorum, geriye dönük uyarlama örnekleri 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 bakacağım herhangi bir kaynak olmadığı için JavaScript gibi daha fazla dilde örnekler eklemek kadar yardımcı olmaz. Android istemcisindeki OpenMRS API uç noktalarıyla uğraşma tecrübelerime dayanarak bazı kaliteli örnekler verebilirim. 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 için de örnekler 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 dokümanlarında bulunması gerçekten kullanışlı bir araç. Burada biraz araştırma yaptım. Mevcut statik dokümanlara Swagger-UI spesifikasyonu eklemek çok zor değildir. Gizlemeyi göster açma/kapatma düğmelerini ve elimizdeki promosyon kodu belgesini kullanarak. Bu şekilde, deneme özelliğinin geçerli API spesifikasyonlarıyla 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
Geçerli curl örneklerini kontrol etme
Bu bölüm, bu yıl projenin en önemli aşamalarından biridir. Şu anda GitHub API dokümanlarında yalnızca curl örnekleri bulunmaktadır. Bu örneklerden bazıları doğrudan tarayıcı üzerinden kontrol etmek için demo sunucusunda doğrudan çalıştırılamaz. Mevcut uç noktaların tümünü 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, kaynağı temizlemek gibi işlemlerde durum genellikle geçerli olsa da, tüm olası yanıt kodlarını ve bunları alma nedenini belgelemiş olsak da örnek bir JSON API Yanıtı vermemiz gerektiğini düşünüyorum. Bunun API belgelerindeki örnekleri daha tutarlı hale getireceğini düşünüyorum!!
Çeşitli işlemlerde eksik çalışma örnekleri
Bence bu, daha önce tamamlanan çalışmaların API dokümanlarında yeniden düzenlenmesinin en önemli kısmı olacak. Belgelerde doğrudan cURL ile yürütülebilecek somut örnekler var, ancak bazıları biraz soyut. Bu da deneyimli geliştiricilere iyi bir referans sağlıyor ancak yeni gelenleri rahatsız ediyor. OpenMRS konuşmasındaki bu gönderiden de öğrendiğim gibi, iyi örneklerin paha biçilmez olduğunu söyleyebiliriz. Bu nedenle, pek işe yaramayan söz dizimi vurgulamayı destekleyebiliriz. Bu, seçenek listesiyle birlikte geliyor, bunu burada öğrendiğim gibi oldukça kolay yapıyor.
Burke'nin yayınında, 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ıyor ve şu anda OpenMRS Webservices API'de çalışan geliştiricilerle konuşarak ve toplulukla etkileşime geçerek daha önce belgelenmiş uç noktaları mümkün olduğunca açıklayıcı hale getirmeye çalışıyorum. Tıpkı PR'deki özellik türleriyle ilgili olarak sağladığım kaynak türleriyle ilgili açıklamaları toplamak için yaptığım gibi. Öncelikli olarak işlerim üzerinde gerçekten çalışır, mentorlarımla konuşur, dokümanlara gerçekten değer katan ve öncelikle tamamlanması gereken şeylerin hangileri olduğuna karar veririm.
Kullanım alanlarını açık başlık olarak ekleme
Konu hakkında bilgi edinmek için birçok API belgesine baktım ve bunların hepsinin açık bir başlık olarak kullanım alanları olduğunu gördüm. Ancak kullanım alanlarımız var ve bunların, kaynakların ve alt kaynakların tanımlarından sonra gelen tanımlar ve örnekler içinde bir şekilde kaynaşmış.
Eksik kaynakları bulma ve belgeleme
Mevcut proje durumu için burada listelenen kaynaklar mevcut ancak burada, promosyon belgelerinin en son sürümünü gördüğümde, 2019 Sezonu Dokümanları sırasında diğer kaynaklarda açıklanan açıklamalarla birlikte GitHub'a uygun API dokümanlarındaki mevcut kaynak paketine eklenebilecek birçok kaynak buldum. Dokümanlara eklenmesi gereken konuları tartışıp uygun ş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, API belgelerini genişletmekle ilgili bu proje üzerinde çalışabileceğimi düşünüyorum. Geliştirici olarak çalışmamı kendim olarak görebiliyor ve diğer geliştiricilerin işini gerçekten kolaylaştırıp hafifletmeyeceğini değerlendirebiliyorum. Burada barındırılan kullanıcı dostu belge deposu için kullanılan araçları öğrendim. Restorasyon dokümanlarının iyileştirilmesine yardımcı olmak için Rest API'larını ve araçları daha iyi kavrayabilmem iyi bir fikir.
İlerlemeyi her hafta bir konuşma yayınıyla aktaracağım. Bu gönderi, topluluktan geri bildirim almaya yardımcı olacak ve bu belgeleme döneminden en iyi şekilde yararlanmak için mentorum ve topluluğumla yakın ilişki içinde çalışacak.