توثيق API لمشروعك باستخدام OpenAPI وأمثلة الطلبات

يحتاج مطور الواجهة إلى معرفة اسم الحقل ونوعه وحالات الرد قبل بناء الشاشة، ويحتاج مطور الخادم إلى عقد يطابق ما ينفذه. يسجل OpenAPI هذا الاتفاق في مستند يمكن قراءته والتحقق منه بالأدوات. سنوثق عملية قراءة حجز واحدة؛ المثال لا ينفذ المصادقة أو فحص الملكية، وهما لازمان قبل إتاحة أي حجز خاص.

حدد الطلب وحالات الاستجابة قبل كتابة المواصفة

نريد أن يطلب المستخدم حجزًا بواسطة معرّف صحيح موجب. إذا كان المورد متاحًا في سياق المستخدم المصرح له، يعيد الخادم كائن الحجز. وإذا لم يجده، يعيد خطأ منظمًا. افصل وصف العقد عن طريقة تخزينه؛ المستهلك لا يحتاج معرفة اسم جدول قاعدة البيانات كي يستخدم العملية.

تعرّف المواصفة الرسمية OpenAPI 3.1.1 حقول المستند والمسارات والاستجابات والمخططات. نستخدم هذا الإصدار صراحة للتوافق مع الأدوات الداعمة له، دون الادعاء أنه أحدث إصدار متاح. تحقق من دعم إصدارك في أداة العرض والتحقق التي تختارها.

وثيقة عملية واحدة يمكن قراءتها

احفظ النص باسم openapi.json. عنوان الخادم محلي للتعليم؛ غيّره فقط إلى بيئة تملكها أو تملك تصريح اختبارها.

{
  "openapi": "3.1.1",
  "info": {"title": "Room Booking API", "version": "1.0.0"},
  "servers": [{"url": "http://127.0.0.1:8000"}],
  "paths": {
    "/bookings/{bookingId}": {
      "get": {
        "operationId": "getBooking",
        "summary": "Read one booking",
        "parameters": [{
          "name": "bookingId", "in": "path", "required": true,
          "schema": {"type": "integer", "minimum": 1}
        }],
        "responses": {
          "200": {
            "description": "Booking found",
            "content": {"application/json": {
              "schema": {"$ref": "#/components/schemas/Booking"},
              "example": {"id": 12, "room": "A101",
                "startsAt": "2026-10-29T08:00:00Z",
                "status": "confirmed"}
            }}
          },
          "404": {
            "description": "Booking not found",
            "content": {"application/json": {
              "schema": {"$ref": "#/components/schemas/Problem"},
              "example": {"code": "BOOKING_NOT_FOUND"}
            }}
          }
        }
      }
    }
  },
  "components": {"schemas": {
    "Booking": {
      "type": "object",
      "required": ["id", "room", "startsAt", "status"],
      "properties": {
        "id": {"type": "integer", "minimum": 1},
        "room": {"type": "string", "minLength": 1},
        "startsAt": {"type": "string", "format": "date-time"},
        "status": {"type": "string", "enum": ["confirmed", "cancelled"]}
      }
    },
    "Problem": {
      "type": "object", "required": ["code"],
      "properties": {"code": {"type": "string"}}
    }
  }}
}

الأرقام والأسماء بيانات تعليمية. يشير $ref إلى مخطط داخلي لتجنب تعريف الكائن بصيغ متعارضة. وتمنع قائمة القيم وصف حالة غير موثقة كما لو كانت مقبولة. لكن required لا يفرض وحده تحقق الخادم؛ يجب تنفيذ القاعدة واختبارها، أو استخدام تحقق يتصل فعلًا بالطلب والاستجابة.

طلب مفهوم واستجابة قابلة للمقارنة

curl -i http://127.0.0.1:8000/bookings/12
curl -i http://127.0.0.1:8000/bookings/999999

شغّل الأوامر فقط بعد تشغيل API يطبق العقد وتهيئة بيانات الاختبار. ينبغي التحقق من رمز الحالة وContent-Type وشكل الجسم، لا ظهور النص في المتصفح فقط. المعرّف الثاني لا يضمن عدم الوجود في كل قاعدة؛ استخدم معرّفًا معروفًا أنه غير موجود في بيانات الاختبار.

اربط الوثيقة باختبار العقد

سجّل أداة التحقق وإصدارها ونتيجتها. قد تتعامل أدوات JSON Schema مع format بوصفه وصفًا لا قيدًا مفعلًا افتراضيًا، لذلك اختبر تاريخًا غير صالح عمدًا. وأضف حالات الإدخال غير الصحيح والأخطاء المتوقعة إلى العقد كلما شملها التنفيذ؛ الوثيقة التي تعرض النجاح وحده لا تشرح كيف يبني المستهلك مسار الفشل.

حدّث العقد مع التغيير

اجعل مراجعة API جزءًا من Pull Request. تغيير نوع حقل أو حذفه قد يكسر الواجهة حتى إذا استمر الخادم في العمل. وضح التوافق وطريقة الانتقال، واربط العقد باختبارات تمنع تراجعه. لا تضع Token أو بيانات عميل حقيقية في الأمثلة أو سجل أوامر curl.

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