ساخت API Document بدون خون ریزی‌!

برای ساخت مستندات API بدون در نظر گرفتن اینکه قراره به صورت عمومی یا داخلی مورد استفاده بشه راه های متفاوتی وجود داره از جمله: Sample Code، فایل متنی ساده شامل Endpoint ها و مقادیری که بعنوان ورودی قبول میکنن و یا استفاده از ابزارهای مثل Postman و Swagger که هر کدوم از این روش ها مزایا و معایب خودشون رو دارن.

اگر توسعه دهنده ی PHP هستید و یا با این زبان آشنایی نسبتا کمی هم داشته باشید میتونید بدون سروکار داشتن با annotation توی سریع ترین زمان مستندات API خودتون رو با فرمت HTML بسازید و در اختیار تیم توسعه دهنده قرار بدین (امکان ساخت مستندات با فرمت های دیگه هم وجود داره).


1- شروع کار (نصب)

بدون در نظر گرفتن اینکه توی چه فریم ورکی مشغول کد زدن هستین یا اینکه پروژه ی شما pure هست میتونید کتابخونه‌ی SibDoc رو از طریق Composer نصب کنید.


composer require mvaliolahi/sibdoc

این کتابخونه از طریق آدرس https://github.com/mvaliolahi/sibdoc قابل دسترسیت.

بعد از نصب کافیه یه Object از کلاس Mvaliolahi\SIbDoc بصورت زیر بسازید:

کد کاملا گویای این هست که هر پارامتر چه وظیفه‌ای رو به عهده داره. علاوه بر آرگمان های بالا میتونید از آرگمان background_color با پاس دادن کد رنگ مورد نظرتون رنگ پس زمینه داکیومنت رو تغییر بدین.

2- تعریف Endpoint ها

با فرض اینکه endpoint ای دارید که اطلاعات یه تراکنش خاص رو نشون میده میتونید به صورت زیر مستندش کنید!


خروجی کد بالا نمای زیرو خواهد داشت:

توجه: کلاس هاس Request و Response رو از Namespace کتابخونه یعنی Mvaliolahi\SibDoc وارد کنید.

اشیاء $request و $response هر دو امکان تعریف Header اختصاصی خودشون رو از طریق متد headers دارن، کافیه یه آرایه انجمنی به این متد پاس بدین. اگه قصد داشته باشید برای تمام Requet ها و یا Response ها هدر پیش فرض تعریف کنید میتونید اینکارو به کمک:

$api->requestHeaders([]) 
$api->responseHeaders([])

انجام بدین.

نکته: هر request میتونه چندین response داشته باشه. در نتیجه میتونید هر تعداد شیء $request با مشخصات مورد نیاز بسازید و به کمک:

 $request->response($anotherResponse)

به request اضافه کنید.


نیاز به توضیح نیست که با شیء api میتونید متدهای get

  • post
  • put
  • patch
  • delete
  • head
  • connect
  • options
  • trace

رو تعریف کنید.

تعریف Group

تعریف گروه به صورت:

انجام میشه.


تعریف Model

برای تعریف مدل کافیه به صورت:

هر تعداد مدل که نیاز دارید تعریف کنید. مدل ها توی خروجی مستندات قابل دسترسی هستن. همچنین میتونید از مدل ها توی بدنه response ها استفاده کنید. مثلا:


3- ذخیره مستندات بصورت HTML

بعد از اینکه تمام endpoint ها و model ها رو تعریف کردید میتونید از طریق متد saveTo مستندات رو در مسیر دلخواه با فرمت html ذخیره کنید.

اگر فایل داکیومنت رو از طریق command-line و یا browser اجرا کنید در مسیر مشخص شده فایلی با اسم document.html ذخیره خواهد شد.


نکته: در صورتی که نیاز داشته باشید داکیومنت رو با فرمت دلخواه مثلا Json یا Markdown ذخیره کنید میتونید کلاس های دلخواه خودتون رو بسازید و اون رو از کلاس Document Generator مشتق کنید. با اینکار به endpoint, group و model هایی که تعریف کردید از طریق متدهایی با همین اسامی دسترسی خواهید داشت.

این کتابخونه از آدرس https://github.com/mvaliolahi/sibdoc قابل دسترسی هست. در صورت علاقه میتونید start بدین :)


کانال تلگرام: http://t.me/cleancasts
http://twitter.com/cleancasts