تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- OpenMRS
- الكاتب التقني:
- Saurabh
- اسم المشروع:
- توسيع مستندات GitHub السهلة الاستخدام لواجهة REST API
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
الهدف الأساسي
يمكنك تحسين مستندات REST API المستنِدة إلى OpenMRS Swagger لإضافة إرشادات حول استخدام هذه الواجهة.
وصف المشروع
واجهة برمجة تطبيقات OpenMRS REST هي إحدى الآليات الرئيسية التي تتيح للمطوّرين الوصول إلى البيانات من OpenMRS. تتوفّر حاليًا مستندات منشأة تلقائيًا استنادًا إلى Swagger لـ OpenMRS Webservices API ومستندات ثابتة مستندة إلى GitHub أيضًا، ومن المفترض أن نوسّع هذه المستندات المستندة إلى GitHub في موسم المستندات هذا.
نظرة عامة موجزة
بعد إجراء بعض الأبحاث حول OpenMRS Talk كما اقترح بيرك، عرفت أنّ هذا المشروع بدأ في عام 2017 كمشروع GSOC. مع Gayan Weerakutti حيث كان الهدف الرئيسي من ذلك هو تحسين الوثائق الحالية لواجهة برمجة تطبيقات OpenMRS REST، من خلال تحسين مواصفات Shagger، وإجراء تحسينات على طريقة إنشاء مواصفات Shagger، من أجل إنشاء نسخة أفضل من وثائق التباهي نفسها. تم تلخيص جميع التفاصيل ذات الصلة التي تم تحقيقها في المشروع هنا في مشاركة محادثة OpenMRS هذه، وكانت مفيدة جدًا.
وفي عام 2019، تمّ تجديد هذا المشروع، وتوقفنا عن إجراء تعديلات على مستندات Swagger لإنتاج صيغ مختلفة. وبدلاً من ذلك، طوّرنا وثائق ثابتة متوافقة مع GitHub، وسنوسّع نطاقها في هذا الموسم من "مستندات Google".
لذا فإن موجز اقتراح المشروع الحالي الذي أنوي وصفه هو :
- تقديم أمثلة بلغات شائعة (على وجه التحديد، جافا وJavaScript)
- إضافة ميزة "الملعب" لوثائق Slate تمامًا مثل ميزة"التجربة" في Swagger
- إعادة الهيكلة وتحسين العمل المنجز حتى الآن.
- العثور على الموارد غير المتوفّرة وإضافتها
- إضافة وصف إضافي إلى قسم وحدة التحكّم في المستندات
الوصف التفصيلي
- أنشئ أمثلة بلغات مختلفة.
نقترح إضافة أمثلة بلغة Java تستند إلى حزمة تطوير البرامج (SDK)، ثم إضافة أمثلة على Retrofit التي نعتقد أنّها ستضيف المزيد من العمق إلى مستنداتنا، لأنّ إضافة أمثلة بلغة أخرى مثل JavaScript لن تكون مفيدة بقدر إضافة أمثلة على Retrofit لأنّنا استخدمنا واجهات برمجة التطبيقات REST هذه أثناء العمل على برنامج OpenMRS Android Client، ولم تكن هناك موارد يمكن الرجوع إليها عندما احتجنا إلى بعض المساعدة في استخدام نقاط النهاية المخصّصة لنظام التشغيل Android. سأتمكّن من تقديم بعض الأمثلة العالية الجودة هنا استنادًا إلى تجربتي في التعامل مع نقاط نهاية واجهة برمجة التطبيقات OpenMRS في برنامج Android. سأناقش هذا الأمر مع المعلمين والعمل على ما يتم تحديده. بالإضافة إلى ذلك، يجب إضافة أمثلة على المصادقة مع خوادم OpenMRS في بعض لغات البرمجة أيضًا، بالإضافة إلى إضافة أمثلة على العمليات المتوافقة. لا تتوفّر لدينا حاليًا سوى أمثلة على curl لهذا الغرض.
- إتاحة استخدام Playground لاختبار أمثلة واجهات برمجة التطبيقات
لقد استخدمت هذه الميزة في مستندات Swagger الخاصة بـ OpenMRS المستضافة على خادم العرض التجريبي، وهي أداة ملائمة جدًا لاستخدامها في أي مستندات لواجهة برمجة التطبيقات. لقد أجريتُ بعض الأبحاث هنا، وتبيّن لي أنّه ليس من الصعب تضمين مواصفات Swagger-UI في المستندات الثابتة الحالية. باستخدام مفاتيح التبديل لإظهار العناصر وإخفائها واستخدام رمز مستندات Swagger الحالي الذي لدينا. بهذه الطريقة، يمكننا أيضًا التأكّد من أنّ ميزة الإصدار التجريبي تظل متوفّرة مع مواصفات واجهة برمجة التطبيقات الحالية، وهذه إحدى الطرق التي نعتقد أنّنا يمكننا من خلالها دمج ميزات "مساحة اللعب" في مستنداتنا الثابتة الحالية.
- إعادة صياغة العمل الذي تمّ إنجازه حتى الآن وتحسينه
التحقّق من أمثلة curl الحالية
هذا القسم هو أحد الجوانب الأساسية لهذا المشروع هذا العام، وفي الوقت الحالي، لا تتوفّر إلا أمثلة على تمرين التجعيد في مستندات GitHub API التي لا يمكن تشغيل بعضها مباشرةً على خادم العرض التوضيحي لفحصها مباشرةً من المتصفح. سأختبر جميع نقاط النهاية الحالية وسأحتفظ بمستند بسيط يحتوي على العديد من الردود التي نحصل عليها عند تنفيذ طلبات التجعيد. سأستخدم Postman بالإضافة إلى ميزة التجربة المضمّنة في مستندات Swagger لتنفيذ هذه المهمة إذا لزم الأمر.
عدم توفّر ردود واجهة برمجة التطبيقات في بعض الأمثلة
تمت إضافة بعض الردود لأمثلة التجعيد الحالية، لكن بعض أمثلة التجعّد لا تحتوي على ردود. أعتقد أنّه حتى إذا لم تكن الردود مطوّلة، وهو ما يحدث عادةً مع عمليات مثل إزالة المورد نهائيًا، يجب أن يكون لدينا مثال لاستجابة JSON API على الرغم من أننا وثقنا جميع رموز الاستجابة المحتملة وسبب جعلها وأعتقد أن ذلك سيجعل الأمثلة في مستندات واجهة برمجة التطبيقات أكثر توحيدًا.
لا تتوفّر أمثلة ناجحة على عمليات مختلفة.
أعتقد أنّ هذا سيكون الجزء الأكثر أهمية من إعادة صياغة العمل الذي تم إنجازه سابقًا في مستندات واجهة برمجة التطبيقات. هناك أمثلة ملموسة في المستندات يمكن تنفيذها مباشرةً باستخدام cURL، ولكن بعضها مجردي إلى حد ما، ما يقدّم مرجعًا جيدًا للمطوّرين ذوي الخبرة، ولكنه يترك الوافدِين الجدد في حالة من الإزعاج. ولأنني تمكنت من جمع ما سأقوله في هذا المنشور في OpenMRS، فإن الأمثلة الجيدة لا تقدر بثمن، وبصرف النظر عن إضافة أمثلة للعمل، يمكننا دعم إبراز بناء الجملة وهو في الواقع ليس كثيرًا، إلا أنه يأتي مرفقًا إلى حد كبير مع العناصر الحاجب التي تجعل ذلك سهل جدًا كما اكتشفت هنا،
كما شدد "بيرك" عدة مرات في مشاركته على تفضيل البساطة والوصف في المستندات بدلاً من واجهة المستخدم الجيدة والواجهة اللامعة، سألتزم بهذه المبادئ وسأحاول جعل نقاط النهاية الموثَّقة سابقًا وصفية قدر الإمكان من خلال التحدث إلى المطوّرين الذين يعملون حاليًا على OpenMRS Webservices API والتفاعل مع المنتدى، تمامًا كما فعلت في مشاركتي حول جمع أوصاف لأنواع السمات لموارد النماذج التي لم تكن واضحة لي في طلب إعادة النظر الذي قدّمته هنا. سأعمل على حلّ المشاكل ذات الأولوية، وأتحدّث إلى خبراء الإرشاد، وأحدّد الأمور التي تضيف قيمة إلى المستندات والتي يجب إكمالها أولاً.
إضافة "حالات الاستخدام" كعنوان واضح
لقد اطّلعت على العديد من وثائق واجهة برمجة التطبيقات لمجرد فهمها ورأيت أن جميع حالات الاستخدام لها حالات استخدام كعنوان رئيسي واضح، على الرغم من أن لدينا حالات استخدام غير مرئية بشكل واضح، إلا أنها مندمجة إلى حد ما داخل التعريفات والأمثلة التي تلي تعريفات الموارد والموارد الفرعية، أعتقد أنه يجب أن نبذل جهدًا لفصل حالات الاستخدام باعتبارها كيانًا منفصلاً في المستندات بدلاً من البحث عن حالات الاستخدام من خلال التعريفات.
العثور على الموارد غير المتوفّرة وتوثيقها
تتضمّن حالة المشروع الحالية مراجع مُدرَجة هنا، ولكن بعد الاطّلاع على أحدث إصدار من مستندات Swagger هنا، تمكّنت من العثور على العديد من المراجع التي يمكن إضافتها إلى مجموعة المراجع الحالية في مستندات واجهة برمجة التطبيقات المتوافقة مع GitHub مع الوصف الذي تمّ إجراؤه مع المراجع الأخرى خلال "موسم المستندات" لعام 2019. سأناقش المواضيع التي يجب إضافتها إلى المستندات وأضيفها بشكل مناسب.
الخاتمة
لقد كنت عضوًا في منتدى OpenMRS منذ فترة. أنا من المساهمين النشطين في مشروع Android Client، حيث أتفاعل مع واجهات برمجة التطبيقات كثيرًا للتفاعل مع الخوادم. وبالتالي، أشعر أنه يمكنني العمل على هذا المشروع لتوسيع نطاق مستندات واجهة برمجة التطبيقات بشكل جيد بما أنه يمكنني بنفسي عرض عملي كمطوِّر وتقييم ما إذا كان يسهِّل عمل المطورين الآخرين أم لا. وقد أصبحت على دراية بالأدوات المستخدمة في مستودع المستندات السهل الاستخدام والمُستضاف هنا، وقد قدّمت العديد من المساهمات في هذا المستودع أيضًا من أجل التعرف على وثائق واجهة برمجة التطبيقات (API) لتحسينها.
سأحرص على مشاركة مستوى التقدّم أسبوعيًا من خلال مشاركة محادثة ستساعد في الحصول على الملاحظات من المنتدى والعمل بشكل وثيق مع المرشد والمنتدى للاستفادة إلى أقصى حد من هذه الفترة من التوثيق.