مشروع OpenMRS

تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.

ملخص المشروع

المؤسسة المفتوحة المصدر:

OpenMRS

الكاتب التقني:

سوراب

اسم المشروع:

توسيع نطاق مستندات GitHub السهلة الاستخدام لواجهة برمجة تطبيقات REST

مدة المشروع:

المدة العادية (3 أشهر)

وصف المشروع

الهدف الأساسي

يمكنك تحسين مستندات واجهة برمجة تطبيقات REST المستندة إلى OpenMRS Swagger لإضافة إرشادات حول استخدام واجهة برمجة التطبيقات.

وصف المشروع

تُعد واجهة برمجة تطبيقات OpenMRS REST إحدى الآليات الرئيسية للمطورين للوصول إلى البيانات من OpenMRS. هناك بالفعل وثائق تم إنشاؤها تلقائيًا بالاستناد إلى Swagger لواجهة برمجة تطبيقات OpenMRS Webservices API ووثائق ثابتة تستند إلى GitHub أيضًا، من المفترض أن نوسع تلك المستندات المستندة إلى GitHub في "موسم المستندات" هذا.

نظرة عامة موجزة

بعد القليل من البحث حول OpenMRS Talk كما اقترح "بورك"، علمت أن هذا المشروع بدأ في عام 2017 كمشروع GSOC. من خلال "غايان وييراكوتي"، كان الهدف الرئيسي هو تحسين المستندات الحالية الخاصة بواجهة OpenMRS REST API، من خلال تحسين مواصفات Swagger الخاصة بها، وذلك من خلال إجراء تحسينات على طريقة إنشاء "مواصفات Swagger" الخاصة بها كي يتم إنشاء نسخة أفضل من مستندات التباهي نفسها. تم تلخيص جميع التفاصيل ذات الصلة التي تم إنجازها في المشروع هنا في منشور OpenMRS الحواري هذا وكانت مفيدة للغاية.

بعد ذلك، في عام 2019، تم تجديد هذا المشروع، وانتقلنا من تعديلات توثيق التباهي لإنتاج أشكال مختلفة حول هذا الموضوع. بدلاً من ذلك، طورنا وثائق ثابتة ومتوافقة مع GitHub وسنوسّعها في هذا الموسم من المستندات.

لذا فإن موجز اقتراح المشروع الحالي الذي أنوي وصفه هو :

1. التوصل إلى أمثلة لبعض اللغات الشائعة (على وجه التحديد جافا وJavaScript).
2. إضافة دعم فوري للمستندات التي تحتوي على عناصر حاجبة تمامًا مثل ميزة "تجربة المستخدم" في"Swagger"
3. إعادة بناء وتحسين العمل المنجز حتى الآن.
4. العثور على الموارد المفقودة وإضافتها.
5. إضافة مزيد من الوصف إلى قسم وحدة التحكّم في المستندات

وصف تفصيلي

1. التوصل إلى أمثلة بلغات مختلفة.

أقترح إضافة أمثلة في JavaScript تستند إلى حزمة SDK ثم إضافة أمثلة تعديل أعتقد أنّها ستضيف المزيد من التفاصيل إلى مستنداتنا، لأنّ إضافة أمثلة بلغة أخرى مثل JavaScript لن يكون مفيدًا بقدر ما تكون إضافة أمثلة للتحديث حيث استخدمت واجهات برمجة تطبيقات REST هذه أثناء العمل على عميل OpenMRS Android، ولم تكن هناك أي موارد للبحث عنها كلما احتجتُ إلى بعض المساعدة في استخدام نقاط النهاية خصيصًا لنظام Android. وسأتمكّن من تقديم بعض الأمثلة عالية الجودة هنا بالاستناد إلى خبرتي في التعامل مع نقاط نهاية واجهة برمجة التطبيقات OpenMRS في برنامج Android. سأناقش هذا الأمر مع المعلمين وأعمل على تحديد ما يتم اتخاذه. بالإضافة إلى ذلك، بالإضافة إلى إضافة أمثلة للعمليات المتوافقة، ينبغي أن نضيف أمثلة للمصادقة مع خوادم OpenMRS في بعض لغات البرمجة أيضًا. لدينا في الوقت الحالي أمثلة فقط للتمرين العضلي.

1. إضافة دعم Playground لاختبار واجهات برمجة التطبيقات

لقد استخدمت هذه الميزة في وثائق التباهي بخدمة OpenMRS المستضافة على خادم العرض التوضيحي، وهي أداة ملائمة حقًا يمكن الحصول عليها في أي من مستندات واجهة برمجة التطبيقات. لقد بحثت في هذا القسم قليلاً، وليس من الصعب تضمين مواصفات Swagger-UI في الوثائق الثابتة الحالية. استخدام خيارات إيقاف/تفعيل الإخفاء واستخدام رمز التوثيق الحالي للدلالة على التباهي الذي لدينا وبهذه الطريقة يمكننا ضمان بقاء ميزة التجربة مباشرة مع المواصفات الحالية لواجهة برمجة التطبيقات، وهذه هي إحدى الطرق التي أعتقد أنه يمكننا دمج ميزات التطبيق الفعلي في وثائقنا الثابتة الحالية.

1. إعادة بناء وتحسين العمل المنجز حتى الآن

جارٍ التحقّق من أمثلة curl الحالية

هذا القسم هو أحد التركيز الرئيسي لهذا المشروع هذا العام، وفي الوقت الحالي، لا توجد سوى أمثلة متعرجة على مستندات واجهة برمجة تطبيقات GitHub، والتي لا يمكن تشغيل بعضها مباشرةً على الخادم التجريبي للتحقق منها مباشرة من المتصفح. سأختبر جميع نقاط النهاية الحالية وسأحتفظ بمستند بسيط يحتوي على أمثلة متنوعة من أمثلة الروابط التي نحصل عليها عند تنفيذ طلبات curl هذه. سأستخدم Postman بالإضافة إلى ميزة التجربة المضمّنة في وثائق التباهي لإنجاز هذه المهمة إذا لزم الأمر.

عدم توفّر ردود واجهة برمجة التطبيقات على بعض الأمثلة

تمت إضافة بعض الاستجابات لأمثلة curl الحالية، لكن بعض أمثلة curl لا تحتوي على استجابات. أعتقد أنه حتى لو لم تكن الردود مطوَّلة وهو ما يحدث عادةً مع عمليات مثل تطهير المورد، يجب أن يكون لدينا مثال لاستجابة JSON API على الرغم من أننا وثقنا جميع رموز الاستجابة الممكنة وسبب الحصول عليها، أعتقد أن هذا سيجعل الأمثلة عبر وثائق واجهة برمجة التطبيقات أكثر توحيدًا !!

أمثلة عمل مفقودة على عمليات مختلفة

أعتقد أنّ هذا سيكون أهم جزء في إعادة تنظيم العمل المُنجَز سابقًا في مستندات واجهة برمجة التطبيقات، وهناك أمثلة ملموسة في الوثائق يمكن تنفيذها مباشرةً باستخدام cURL، لكن بعضها عبارة عن بعض البيانات التجريدية قليلاً ما يوفّر مرجعًا جيدًا للمطوّرين ذوي الخبرة ولكنه يترك المستخدمين الجدد في حالة إزعاج. وبقدر ما أستطيع أن أجمع من هذه المشاركة في OpenMRS أن الأمثلة الجيدة لا تقدر بثمن، ولذلك بخلاف إضافة أمثلة على العمل، يمكننا دعم تسليط الضوء على بناء الجملة وهو في الواقع ليس كثيرًا، ولكنه يأتي إلى حد كبير مع عنصر حاجب مما يجعل هذا الأمر سهلاً تمامًا كما اكتشفتُ هنا،

وكما أكد "بيرك" في منشوره عدة مرات مفضَّلاً البساطة والوصف في المستندات بدلاً من واجهة مستخدم جيدة وواجهة لامعة، ألتزم بهذه المبادئ وأحاول أن أجعل نقاط النهاية التي تم توثيقها سابقًا وصفية قدر الإمكان من خلال التحدث إلى المطورين الذين يعملون حاليًا على واجهة برمجة تطبيقات OpenMRS Webservices API وإشراك المنتدى، تمامًا كما فعلت في مشاركة الحديث لجمع أوصاف أنواع السمات التي لم تكن واضحة لي في النماذج الصحفية. سأعمل حقًا على أولوية الأمور بحكمة، وأتحدث مع المرشدين، وأقرر الأمور التي تضيف قيمة إلى المستندات والتي يجب إنجازها أولاً.

إضافة حالات الاستخدام كعنوان صريح

لقد اطّلعت على العديد من مستندات واجهة برمجة التطبيقات لفهمها فقط، ورأيت أنّ جميع حالات الاستخدام كانت لها حالات استخدام كعنوان واضح، على الرغم من أنّ لدينا حالات استخدام غير مرئية بوضوح، إلا أنّها مدمجة إلى حد ما في التعريفات والأمثلة التي تلي تعريفات الموارد والموارد الفرعية، وأعتقد أنّه يجب علينا بذل جهد لفصل حالات الاستخدام ككيان منفصل في المستندات كي لا يتمكّن المطوّرون من البحث في هذه التعريفات.

1. البحث عن الموارد المفقودة وتوثيقها

   تحتوي حالة المشروع الحالية على موارد مدرجة هنا، ولكن عند رؤية أحدث إصدار من وثائق التباهي هنا، يمكنني معرفة العديد من الموارد التي يمكن إضافتها إلى مجموعة الموارد الحالية في مستندات واجهة برمجة التطبيقات المتوافقة مع GitHub مع الوصف كما تم إنجازه مع الموارد الأخرى خلال موسم المستندات لعام 2019. سأناقش المواضيع التي يجب إضافتها إلى المستندات وإضافتها بشكل مناسب.

الخاتمة

لقد كنت جزءًا من منتدى OpenMRS لفترة من الوقت حتى الآن. أنا مساهم نشط في مشروع عميل Android حيث أتفاعل مع واجهات برمجة التطبيقات بشكل متكرر للتفاعل مع الخوادم. وبالتالي، أشعر أنه يمكنني العمل في هذا المشروع المتمثل في توسيع مستندات واجهة برمجة التطبيقات بشكل جيد حيث يمكنني عرض عملي كمطور بنفسي وتقييم ما إذا كان ييسر عمل المطورين الآخرين أم لا، وقد أصبحت على دراية بالأدوات المستخدمة في مستودع وثائق سهل الاستخدام المستضاف هنا، وقد قدمت العديد من المساهمات في هذا المستودع أيضًا من أجل التعرف على المستودع والأدوات، مثل تحسين واجهة برمجة التطبيقات، مثل تحسين واجهة برمجة تطبيقات

سأحرص على مشاركة مستوى التقدم أسبوعيًا من خلال نشر نقاش سيساعدني في الحصول على آراء وملاحظات من المنتدى والعمل بشكل وثيق مع مرشدي والمنتدى للاستفادة إلى أقصى حد من هذه الفترة من التوثيق.