این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه ی پروژه
- سازمان متن باز:
- OpenMRS.org
- نویسنده فنی:
- batbrain7
- نام پروژه:
- اسناد OpenMRS REST API
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
من پیشنهاد خود را به بخش‌های مختلف تقسیم می‌کنم و جریانی را مانند اسناد Google Maps API و اسناد Github API دنبال می‌کنم.
جدا از اینها، من همچنین می خواهم یک ساختار readme برای اسناد API پیشنهاد کنم که توسط realworld.io انجام می شود: https://github.com/gothinkster/realworld/tree/master/api
من شخصاً درک و استفاده از این مستندات را بسیار آسان یافتم.
پیشنهاد من عمدتاً شامل 3 بخش است:
بخشی که به معرفی سریع API، OpenMRS و نحوه استفاده از API و مواردی که بعد از آن می‌آید می‌پردازد.
نحوه به دست آوردن کلید API و احراز هویتی که به طور کلی برای ایجاد درخواست API مورد نیاز است. این شامل نمونه‌ای از انواع احراز هویت موجود در API و کلیدها و مقادیری است که باید برای آن وجود داشته باشد، همچنین انواع مقادیری که مطابق با کلید آن بخش پذیرفته شده‌اند. یک نمونه کد به هر زبانی به نحوه نوشتن سرصفحه ها و فرمت های پاسخ و سایر پارامترهای پرس و جو در API کمک می کند و روشن می کند.
انواع پاسخ هایی که توسط API واکشی می شوند، انواع JSON یا هر نوع نتیجه دیگری که توسط API ها برگردانده می شود باید ذکر شود.
مسیرهای مختلف API و تمام پارامترهایی که باید همراه با آن ها، هدرها و موارد دیگر ارسال شوند. هر API با نمونه‌های کد به چند زبان کمک می‌کند که نحوه درخواست را در هنگام نوشتن کد برای آن توضیح می‌دهد، جدای از آن کدهای خطای کلی که ممکن است با هر API با آن مواجه شود نیز باید ذکر شود.
این یک ایده کلی از نحوه تعریف مستندات برای REST API است.
برنامه زمانبندی پروژه به شرح زیر است:
1 آگوست - 1 سپتامبر
با مربی من آشنا شوید و در مورد سطح مستندات مورد نیاز در بخش‌های مختلف پایگاه کد با عمق بیشتری بحث کنید و همچنین در مورد چگونگی انجام مستندات سطح پایین در مقابل سطح بالا بحث کنید. من همچنین این زمان را صرف درک پایگاه کد و مطالعه مفاهیم خواهم کرد تا بتوانم آنها را بهتر مستند کنم.
هفته 1 و 2
من راهنمای مشارکت‌کنندگان را به‌روزرسانی و گسترش خواهم داد. من مستندات مربوط به نحوه ساخت کد منبع را بهبود خواهم داد. من همچنین یک بخش مستندساز اضافه خواهم کرد که چگونه مشارکت کنندگان جدید می توانند در مستندسازی کمک کنند. من اسناد مختلف API را مطالعه می کنم و با مقدمه شروع می کنم و احراز هویت را برای API اضافه می کنم.
هفته 3 تا 8
من مسیرها و پاسخ‌های API را به همراه چند نمونه کد برای هر نوع API اضافه می‌کنم (ممکن است انواع مشابهی از API وجود داشته باشد).
هفته 9 و 10
ساختار اسناد API را با استفاده از پیوندها اضافه کنید، به عنوان مثال یک فهرست پیوندی برای اسناد طولانی API و آن را بر اساس متفاوتی مانند بخش های کد، نمای کلی، پارامترها، نقاط پایانی ریشه تقسیم کنید.
هفته پایانی
من از هفته آخر برای تهیه گزارش نهایی خود از کارهای انجام شده در دوره اسناد 12 هفته ای خود استفاده خواهم کرد. من همچنین این زمان را صرف بررسی و نهایی کردن مستندات خواهم کرد.