توثيق واجهة برمجة التطبيقات في Kawkab

// إعدادات توثيق API
docs: {
  // تفعيل أو تعطيل توثيق API
  enable: true,
 
  // عنوان توثيق API
  title: "API Documentation",
 
  // وصف توثيق API
  description: "Documentation for API endpoints.",
 
  // مسار تخزين الوثائق المُنشأة
  path: "storage/private/docs",
},

npm run kawkab docs:make

/storage/private/docs

/**
 * @api {method} path [title]
 */

/**
 * @api {get} /users/:id Get User Information
 */

/**
 * @apiName GetUserProfile
 */

/**
 * @apiName GetUserProfile
 */

/**
 * @apiGroup Users
 */

/**
 * @apiGroup Users
 */

/**
 * @apiVersion 1.2.0
 */

/**
 * @apiVersion 1.2.0
 */

/**
 * @apiDescription This endpoint allows you to get complete user information.
 * You can use it to retrieve:
 * - Personal Information
 * - Settings
 * - Preferences
 */

/**
 * @apiDescription This endpoint allows you to get complete user information.
 * You can use it to retrieve:
 * - Personal Information
 * - Settings
 * - Preferences
 */

/**
 * @apiParam [(المجموعة)] {النوع} الاسم [=القيمة_الافتراضية] [الوصف]
 */

/**
 * @apiParam {String} username Username (3-20 characters)
 * @apiParam {String} [email] Email address
 * @apiParam {Number} [age=18] Age
 * @apiParam (Authentication) {String} api_key API Key
 */

/**
 * @apiSuccess [(المجموعة)] {النوع} الحقل الوصف
 */

/**
 * @apiSuccess {Boolean} status Operation status
 * @apiSuccess {Object} data User data
 * @apiSuccess {Number} data.id User ID
 * @apiSuccess {String} data.username Username
 */

/**
 * @apiError [(المجموعة)] {النوع} الحقل الوصف
 */

/**
 * @apiError UserNotFound User was not found
 * @apiError (Authentication) InvalidAPIKey Invalid API key
 */

/**
 * @apiHeader [(المجموعة)] {النوع} الحقل الوصف
 */

/**
 * @apiHeader {String} Authorization Bearer token
 * @apiHeader {String} [Accept-Language] Response language
 */

/**
 * @apiExample {النوع} العنوان
 *    المثال
 */

/**
 * @apiExample {curl} Example usage:
 *    curl -X POST \
 *      http://api.example.com/users \
 *      -H 'Authorization: Bearer token' \
 *      -d '{"username":"john","email":"john@example.com"}'
 */

/**
 * @apiSuccessExample {النوع} العنوان
 *    المثال
 *
 * @apiErrorExample {النوع} العنوان
 *    المثال
 */

/**
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "status": true,
 *       "data": {
 *         "id": 1,
 *         "username": "john",
 *         "email": "john@example.com"
 *       }
 *     }
 *
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "status": false,
 *       "error": "UserNotFound",
 *       "message": "User not found"
 *     }
 */

/**
 * @apiDefine اسم_الكتلة
 *    محتوى_الكتلة
 */
 
/**
 * @apiUse اسم_الكتلة
 */

/**
 * @apiDefine CommonErrors
 * @apiError NotFound Resource not found
 * @apiError Unauthorized Unauthorized access
 */
 
/**
 * @api {get} /users/:id
 * @apiUse CommonErrors
 */

/**
 * @apiDeprecated [الرسالة]
 */

/**
 * @apiDeprecated Use /api/v2/users instead
 */

import { BaseController, inherit } from "kawkab";
 
export default class extends inherit(BaseController) {
  /**
   * @api {get} / الحصول على رسالة الترحيب
   * @apiName GetWelcomeMessage
   * @apiGroup Kawkab
   * @apiVersion 1.0.0
   *
   * @apiSuccess {Boolean} status حالة استجابة API.
   * @apiSuccess {String} message رسالة الترحيب لإطار عمل Kawkab.
   *
   * @apiSuccessExample {json} مثال الاستجابة الناجحة:
   *     HTTP/1.1 200 OK
   *     {
   *       "status": true,
   *       "message": "مرحباً بك في إطار عمل Kawkab 🚀 - رفيقك السريع لإنشاء APIs بأناقة وبساطة لا مثيل لها. دعنا نبني شيئاً استثنائياً معاً!"
   *     }
   */
  async get() {
    return {
      status: true,
      message:
        "مرحباً بك في إطار عمل Kawkab 🚀 - رفيقك السريع لإنشاء APIs بأناقة وبساطة لا مثيل لها. دعنا نبني شيئاً استثنائياً معاً!",
    };
  }
}

@api {method} /path وصف نقطة النهاية

@apiName اسم_الدالة

@apiGroup اسم_المجموعة

@apiVersion 1.0.0

@apiParam {النوع} الاسم الوصف

@apiSuccess {النوع} الاسم الوصف

@apiError {النوع} الاسم الوصف

/**
 * @api {post} /user Create New User
 * @apiName CreateUser
 * @apiGroup Users
 * @apiVersion 1.0.0
 *
 * @apiParam {String} username Username (3-20 characters)
 * @apiParam {String} email Email address
 * @apiParam {String{6..}} password Password (minimum 6 characters)
 *
 * @apiSuccess {Boolean} status Operation status
 * @apiSuccess {Object} user Created user data
 * @apiSuccess {Number} user.id User ID
 * @apiSuccess {String} user.username Username
 * @apiSuccess {String} user.email Email address
 *
 * @apiError UserExists User already exists
 * @apiError InvalidInput Invalid input data
 */

/**
 * @api {get} /products Search Products
 * @apiName SearchProducts
 * @apiGroup Products
 * @apiVersion 1.0.0
 *
 * @apiParam {String} [query] Search query
 * @apiParam {Number} [page=1] Page number
 * @apiParam {Number} [limit=10] Results per page
 *
 * @apiParamExample {json} Request example:
 *     {
 *       "query": "phone",
 *       "page": 1,
 *       "limit": 10
 *     }
 *
 * @apiSuccess {Boolean} status Operation status
 * @apiSuccess {Object[]} products Product list
 * @apiSuccess {Number} total Total results
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "status": true,
 *       "products": [
 *         {
 *           "id": 1,
 *           "name": "Smartphone",
 *           "price": 999.99
 *         }
 *       ],
 *       "total": 1
 *     }
 */

/**
 * @api {post} /users Create New User
 * @apiVersion 1.0.0
 * @apiName CreateUser
 * @apiGroup Users
 * @apiDescription Create a new user account in the system
 *
 * @apiHeader {String} Authorization Bearer token
 *
 * @apiParam {String} username Username (3-20 characters)
 * @apiParam {String} email Email address
 * @apiParam {String{6..}} password Password (minimum 6 characters)
 * @apiParam {Object} [profile] User profile information
 * @apiParam {String} [profile.fullName] Full name
 * @apiParam {Number} [profile.age] Age
 *
 * @apiSuccess {Boolean} status Operation status
 * @apiSuccess {Object} data Created user data
 * @apiSuccess {Number} data.id User ID
 * @apiSuccess {String} data.username Username
 * @apiSuccess {String} data.email Email address
 * @apiSuccess {Object} data.profile Profile information
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 201 Created
 *     {
 *       "status": true,
 *       "data": {
 *         "id": 1,
 *         "username": "john",
 *         "email": "john@example.com",
 *         "profile": {
 *           "fullName": "John Doe",
 *           "age": 25
 *         }
 *       }
 *     }
 *
 * @apiError ValidationError Input validation failed
 * @apiError UserExists User already exists
 *
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 400 Bad Request
 *     {
 *       "status": false,
 *       "error": "ValidationError",
 *       "message": "Invalid email format"
 *     }
 */