بعد الإنتهاء من تجهيز API، فإنه يفضل أن يتم عمل توثيق documentation له، وإرسالة لمبرمج Front End أو مبرمج تطبيقات الهواتف، وذلك حتى يستطيع فهم المشروع والروابط التي يجب أن يتعامل معها، والحقول الإجبارية والإختيارية... وغيرها من الأمور المتعلقة بالـ API.

يوجد مجموعه من الأدوات التي تساعدنا في إتمام هذا العمل، لكن في هذه المقالة سوف أتطرق لأداة Scribe وذلك لسهولة التعامل معها.

توثيق API بإستخدام أداة Scribe

تثبيت الأداة من هنا

composer require --dev knuckleswtf/scribe

عمل publish 

php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config

تعديل إعدادات scribe.php

بعد عمل publish سيتم إنشاء ملف باسم scribe.php في المسار config/scribe.php نذهب لهذا الملف ، وبما إننا نريد عمل توثيق فقط للـ api فنقوم بتعديل prefix إلى

'prefixes' => ['api/*'],

تحضير ملف routes/api.php

هذا الملف يجب أن تكون routes محضرة به بشكل مسبق، حيث سيقوم scribe بقرائتها وإنشاء التوثيق بشكل تلقائي لها.

Route::apiResource('brands',BrandController::class);
Route::get('products',[ProductController::class,'index']);

تحضير ملف .env

حيث يجب تعديل baseUrl للنطاق الذي تعمل عليه، هنا لدي تم بما إنني أستخدام localhost فإن الدومين لدي هو test.test بالتالي سيتم تعديل baseUrl إلى

APP_URL=http://www.test.test

عرض scribe api documentation

بعد الإنتهاء من الإعدادات ولعرض documentation

ننفذ الأمر 

php artisan scribe:generate

 نضع كلمة docs بعد domain

http://www.test.test/docs/

ملفات scribe documentation يتم تخزينها في المسار 

Public/docs

لمشاهدة routes نذهب إلى التبويب Endpoints

عند الضغط على أي Endpoint سوف تظهر النتائج مع status code على الجهة المقابلة. 

بعض الإعدادات لشكل documentation

لإضافة الشعار

نذهب للملف scribe.php ومن ثم نغير قيمة logo من false إلى رابط الصورة

'logo' => 'https://etharshrouf.com/front/img/ethar.png',

لوضع إسم المشروع

نذهب للملف scribe.php ومن ثم نعدل في intro_text

'intro_text' => <<<INTRO
Welcome To TEST API Documentation. 

ومن ثم ننفذ الأمر

php artisan scribe:generate

حيث إنه يجب تنفيذ الأمر بعد أي تعديل نقوم به.

جعل  Endpoints أكثر قابلية للقراءة.

تعديل أسماء Endpoints

لو نظرنا إلى endpints نجد أن قرائتها غير مريحة لكن يمكننا التعديل عليها، على سبيل المثال إن أردنا تعديل api/brands إلى Get Brands

للقيام بذلك نستخدم ما يسمى dock block حيث يتم وضعها فوق دالة عرض brands

/**
 * Get Brands.
 *
 * List All Brands
 */
public function index(){
    return BrandResource::collection(Brand::select('id','name','created_at',)->latest()->get());
}

ننفذ الأمرر 

Php artisan scribe:generate

كما يمكن إستخدام dock block مع جميع الدوال

إستخدام menu items :

 حيث يمكن لنا ترتيب عرض endpints فمثلا جميع endpints الخاصه بالـ brand يتم عرضها تحت تبويب brand وجميع endpints الخاصه بالـ products أن يتم عرضها تحت تبويب products وهكذا.

للقيام بذلك نستخدم dock block التالي فوق الـ controller

/**
 * @group   Brands.
 *
 * Managing Brands
 */
class BrandController extends Controller
{
 

توثيق forms

كما يمكن أيضا إظهار الحقول التي يجب إرسالها مع نوعها وحالتها هل هي إجبارية أم لا في التوثيق وذلك من خلال إستخدام dock block مع @bodyParam

/**
 * POST Brand.
 *
 * Create New Brand
 *
 * @bodyParam name string required Name of brand. Example: "Clothing
 */
public function store(BrandStoreRequest $request)
{

كما نلاحظ بالصوره أنه ظهر إسم الحقل name ونوعه string وهو إجباري لأنه لم يظهر بجانبه كلمة optional.