پروژه OpenMRS

این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.

خلاصه ی پروژه

سازمان منبع باز:

OpenMRS

نویسنده فنی:

سوراب

نام پروژه:

گسترش اسناد GitHub کاربر پسند برای REST API

طول پروژه:

طول استاندارد (3 ماه)

شرح پروژه

هدف اصلی

اسناد REST API مبتنی بر OpenMRS Swagger را برای افزودن راهنمایی در مورد استفاده از API تقویت کنید.

شرح پروژه

OpenMRS REST API یکی از مکانیسم های کلیدی برای توسعه دهندگان برای دسترسی به داده های OpenMRS است. در حال حاضر یک سند تولید خودکار مبتنی بر Swagger از OpenMRS Webservices API و یک مستندات ثابت مبتنی بر GitHub نیز وجود دارد، ما قرار است این مستندات مبتنی بر GitHub را در این فصل از Docs گسترش دهیم.

بررسی اجمالی

پس از کمی تحقیق در مورد OpenMRS Talk همانطور که برک پیشنهاد کرد، متوجه شدم که این پروژه در سال 2017 به عنوان یک پروژه GSOC شروع شد. با Gayan Weerakutti که در آن هدف اصلی بهبود اسناد موجود OpenMRS REST API بود، با بهبود مشخصات Swagger آن و از طریق بهبود در نحوه تولید مشخصات Swagger آن به طوری که نسخه بهتری از خود مستندات Swagger ایجاد شود. تمام جزئیات مرتبط انجام شده در پروژه در اینجا در این پست گفتگوی OpenMRS خلاصه شد و بسیار مفید بود.

سپس، در سال 2019، این پروژه بازسازی شد، و ما از بهینه سازی اسناد Swagger استفاده کردیم و تغییراتی در این زمینه ایجاد کردیم. درعوض، ما یک سند استاتیک سازگار با GitHub ایجاد کردیم که می‌خواهیم آن را در این فصل از Docs گسترش دهیم.

بنابراین مختصری از پیشنهاد پروژه فعلی که قصد توضیح آن را دارم این است:

1. ارائه مثال هایی در برخی از زبان های رایج (به طور خاص به جاوا و جاوا اسکریپت اشاره شد).
2. اضافه کردن پشتیبانی زمین بازی برای اسناد تخته سنگ درست مانند ویژگی Swagger ""امتحان"".
3. بازسازی و بهبود کارهای انجام شده تا کنون.
4. یافتن و افزودن منابع از دست رفته
5. اضافه کردن کمی توضیحات بیشتر به بخش کنسول اسناد

توصیف همراه با جزئیات

1. مثال هایی به زبان های مختلف بیاورید.

من پیشنهاد می‌کنم نمونه‌هایی را در جاوا اضافه کنید که مبتنی بر SDK باشد و سپس نمونه‌هایی را اضافه کنید که فکر می‌کنم به مستندات ما عمق بیشتری می‌دهد، زیرا افزودن مثال‌ها به یک زبان دیگر مانند جاوا اسکریپت به اندازه افزودن نمونه‌های مقاوم‌سازی کمک نمی‌کند. از این APIهای REST در حین کار بر روی OpenMRS Android Client استفاده کرده‌ام، و هیچ منبعی برای جستجوی هر زمان که برای استفاده از نقاط پایانی مخصوص اندروید نیاز داشتم، وجود نداشت. و من می‌توانم با توجه به تجربه‌ای که در مورد نقاط پایانی OpenMRS API در کلاینت Android داشته باشم، به‌طور جدی نمونه‌های باکیفیتی در اینجا ایجاد کنم. من در این مورد با مربیانم صحبت خواهم کرد و روی آنچه تصمیم گرفته می شود کار خواهم کرد. همچنین به غیر از افزودن نمونه هایی برای عملیات پشتیبانی شده، باید نمونه هایی برای احراز هویت با سرورهای OpenMRS در برخی از زبان های برنامه نویسی نیز اضافه کنیم. ما در حال حاضر فقط نمونه های فر برای این کار داریم.

1. افزودن پشتیبانی Playground برای آزمایش نمونه های API

من از این ویژگی در مستندات swagger OpenMRS که در سرور آزمایشی میزبانی شده است استفاده کرده ام، و این ابزار واقعاً مناسبی است که در هر سند API وجود دارد. من در اینجا کمی تحقیق کردم، و گنجاندن مشخصات Swagger-UI در اسناد ثابت فعلی چندان دشوار نیست. با استفاده از ضامن‌های show hide و استفاده از کد مستندات swagger فعلی که داریم. به این ترتیب حتی می‌توانیم اطمینان حاصل کنیم که ویژگی آزمایشی با مشخصات API فعلی باقی می‌ماند، این یکی از راه‌هایی است که معتقدم می‌توانیم ویژگی‌های زمین بازی را در اسناد ثابت فعلی خود ادغام کنیم.

1. بازسازی و بهبود کارهای انجام شده تا کنون

بررسی نمونه‌های حلقه فعلی

این بخش یکی از تاکیدات اصلی این پروژه در سال جاری است، در حال حاضر، فقط نمونه های curl در اسناد GitHub API وجود دارد که برخی از آنها را نمی توان مستقیماً روی سرور آزمایشی اجرا کرد تا مستقیماً از مرورگر بررسی شود. من تمام نقاط پایانی فعلی را آزمایش می‌کنم و یک سند ساده با پاسخ‌های نمونه‌های curl مختلف که در اجرای آن درخواست‌های curl دریافت می‌کنیم، حفظ می‌کنم. من از Postman علاوه بر ویژگی آزمایش داخلی در اسناد swagger برای انجام این کار در صورت نیاز استفاده خواهم کرد.

پاسخ‌های API در برخی از نمونه‌ها وجود ندارد

برخی از پاسخ‌ها برای نمونه‌های curl حاضر اضافه شده‌اند، اما برخی از نمونه‌های curl پاسخی ندارند. من فکر می‌کنم حتی اگر پاسخ‌ها پرمخاطب نباشند، که معمولاً در عملیات‌هایی مانند پاک کردن منبع اتفاق می‌افتد، باید یک نمونه پاسخ JSON API داشته باشیم، اگرچه همه کدهای پاسخ ممکن و دلیل دریافت آنها را مستند کرده‌ایم، فکر می‌کنم این باعث می‌شود نمونه در سراسر اسناد API یکنواخت تر!

نمونه های کار در عملیات های مختلف از دست رفته است

من فکر می‌کنم این مهم‌ترین بخش بازسازی کارهای انجام‌شده قبلی در مستندات API خواهد بود، نمونه‌های عینی در مستندات وجود دارد که می‌توان مستقیماً با cURL اجرا کرد، اما برخی از آنها کمی انتزاعی هستند که ارجاع خوبی به تجربه‌ها می‌کند. توسعه دهندگان اما تازه واردها را در حالت ناراحتی رها می کند. همانطور که می توانم از این پست در بحث OpenMRS دریافتم که نمونه های خوب قیمتی ندارند، بنابراین جدا از افزودن نمونه هایی از کار، می توانیم از برجسته سازی نحو پشتیبانی کنیم که در واقع کار چندانی نیست، تقریباً همراه با تخته سنگ است که انجام این کار را همانطور که من انجام می دهم بسیار آسان می کند. اینجا فهمیدم

همانطور که بورک بارها در پست خود تاکید کرده است که سادگی و توصیف را در اسناد به جای رابط کاربری خوب و رابط درخشان ترجیح می دهد، من به این اصول پایبند هستم و سعی می کنم با صحبت با توسعه دهندگانی که در حال حاضر روی آن کار می کنند، نقاط پایانی مستند قبلی را تا حد امکان توصیفی کنم. OpenMRS Webservices API و درگیر کردن جامعه، درست مانند کاری که در پست گفتگو برای جمع آوری توضیحات برای انواع ویژگی ها برای منابع فرم ها انجام دادم که در روابط عمومی من در اینجا برای من واضح نبود. من واقعاً روی چیزهایی که اولویت دارند کار می‌کنم، با مربیانم صحبت می‌کنم، و تصمیم می‌گیرم که کدام چیزها واقعاً به اسناد ارزش می‌بخشند و باید ابتدا انجام شوند.

افزودن موارد استفاده به عنوان یک عنوان صریح

من بسیاری از اسناد API را فقط برای فهمیدن آنها دیده ام و دیدم که همه آنها موارد استفاده را به عنوان یک عنوان صریح داشتند، اگرچه موارد استفاده داریم که به صراحت قابل مشاهده نیستند و تا حدودی در تعاریف و مثال های زیر ترکیب شده اند. پس از تعاریف منابع و زیرمنابع، من فکر می کنم ما باید تلاش کنیم تا Use-Case ها را به عنوان یک موجودیت جداگانه در مستندات جدا کنیم تا توسعه دهندگان واقعاً مجبور نباشند در تعاریف استنباط کننده موارد استفاده جستجو کنند، بلکه فقط می توانند به آنها نگاه کن

1. یافتن و مستندسازی منابع از دست رفته

   وضعیت فعلی پروژه دارای منابعی است که در اینجا فهرست شده است، اما با دیدن آخرین نسخه مستندات swagger در اینجا، می توانم منابع زیادی را پیدا کنم که می توانند به مجموعه منابع فعلی در اسناد API دوستانه GitHub با توضیحاتی که با سایر اسناد انجام شده است اضافه شوند. منابع در طول فصل اسناد 2019. من در مورد موضوعاتی که باید به اسناد اضافه شوند بحث خواهم کرد و آنها را به طور مناسب اضافه خواهم کرد.

نتیجه

من مدتی است که بخشی از انجمن OpenMRS هستم. من یک مشارکت کننده فعال در پروژه Android Client هستم که در آن اغلب برای تعامل با سرورها با API ها تعامل دارم. از این رو، احساس می‌کنم می‌توانم روی این پروژه گسترش اسناد API به خوبی کار کنم، زیرا می‌توانم کار خود را به عنوان یک توسعه‌دهنده ببینم و ارزیابی کنم که آیا واقعاً کار توسعه‌دهندگان دیگر را آسان می‌کند یا خیر، با ابزارهای مورد استفاده برای آن آشنا شده‌ام. مخزن اسناد کاربرپسندی که در اینجا میزبانی شده است، من نیز به منظور آشنایی با مخزن و ابزارها مانند slateUI، چندین مشارکت در این مخزن انجام داده ام، از آنجایی که تصور می شود یک API به خوبی اسناد آن است، بنابراین من دوست دارم آن را بسازم. API های OpenMRS Rest با بهبود اسناد آن کمی بهتر است.

من مطمئن خواهم شد که پیشرفت هفتگی را با یک پست گفتگو در میان می‌گذارم که به دریافت بازخورد از جامعه کمک می‌کند و در ارتباط نزدیک با مربی و جامعه خود برای به دست آوردن بهترین نتیجه از این دوره مستندسازی کار می‌کنم.