DEV Community

Cover image for كيف تصمم واجهات برمجة التطبيقات من سطر الأوامر
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيف تصمم واجهات برمجة التطبيقات من سطر الأوامر

تبدأ معظم دروس تصميم واجهات برمجة التطبيقات (API) بالفأرة: افتح محررًا مرئيًا، أضف مخططًا، وانقر لإدخال الحقول. لكن هذا لا يناسب فرق التطوير التي تحفظ العقد في Git، وتراجعه عبر طلبات السحب، وتتحقق منه في CI. في هذا السياق، صمّم واجهة API بالطريقة نفسها التي تنشر بها: كنص قابل للمراجعة، وأوامر قابلة للتكرار، وخطوات يمكن تشغيلها من الطرفية.

جرّب Apidog اليوم

يعرض هذا الدليل مسارين عمليين:

  1. مسار مفتوح المصدر: OpenAPI + Spectral + Redocly CLI + openapi-generator.
  2. مسار Apidog CLI: إدارة المخططات ونقاط النهاية والمصادقة داخل مشروع واحد من الطرفية.

للتفاصيل المفاهيمية، راجع كيفية تصميم واجهة برمجة تطبيقات وتصميم واجهات برمجة تطبيقات REST.

إذا كنت ستستخدم Apidog، ثبّت CLI وسجّل الدخول أولًا. يشرح دليل تثبيت Apidog CLI التثبيت والمصادقة، بينما يعرض الدليل الكامل لـ Apidog CLI مجموعات الأوامر المتاحة.

المسار المفتوح المصدر: التأليف، التدقيق، التجميع، التوليد

يعتمد هذا المسار على أدوات مستقلة تربطها في pipeline واحد. احتفظ بمواصفة OpenAPI في Git، ثم شغّل كل خطوة من الطرفية. هذا مناسب لسير عمل تصميم API الأصيل لـ Git الذي يمنحك تحكمًا كاملًا في الملفات والأدوات.

1. ألّف مستند OpenAPI

أنشئ ملفًا باسم openapi.yaml:

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: An order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]
Enter fullscreen mode Exit fullscreen mode

عندما يكبر العقد، قسّمه إلى ملفات منفصلة واستخدم $ref. بهذه الطريقة تصبح المخططات قابلة للمراجعة بشكل مستقل.

2. دقّق المواصفة باستخدام Spectral

استخدم Spectral لاكتشاف أخطاء مثل غياب operationId أو الاستجابات غير الموثقة أو عدم اتساق التسمية:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

يُرجع Spectral رقم السطر ومستوى الخطورة لكل مخالفة. في CI، اعتبر رمز الخروج غير الصفري فشلًا للبناء.

يمكنك أيضًا استخدام Redocly CLI أو vacuum كبديل. المهم هو أن يكون التدقيق خطوة مستقلة ومبكرة في المسار.

3. اجمع الملفات باستخدام Redocly CLI

إذا استخدمت ملفات متعددة و$ref، اجمع المواصفة في ملف واحد قبل التوليد أو النشر:

npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

يحل الأمر جميع مراجع $ref وينتج أثرًا واحدًا مناسبًا للأدوات اللاحقة. يدعم Redocly أيضًا redocly lint، ويمكنك مراجعة وثائق CLI الرسمية للأوامر الأخرى.

4. ولّد كود الخادم أو SDK

استخدم openapi-generator لتوليد هيكل متوافق مع العقد:

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

غيّر المولد حسب بيئتك:

# Flask
-g python-flask

# Go
-g go-server
Enter fullscreen mode Exit fullscreen mode

المسار الكامل يصبح:

spectral lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

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

مسار Apidog CLI: إدارة التصميم في مشروع واحد

يتيح apidog-cli إدارة المخططات ونقاط النهاية والمجلدات والمصادقة والاستيراد والتصدير والمحاكاة من الطرفية ضمن مشروع واحد.

مهم: لا يقوم Apidog بتدقيق أسلوب OpenAPI أو فرض دليل أنماط. إذا كنت تحتاج إلى lint، استمر في استخدام Spectral أو vacuum. كما أن Apidog منتج تجاري مع طبقة مجانية، وليس مشروعًا مفتوح المصدر. راجع بدائل Swagger لتصميم واختبار API لمعرفة متى يكون هذا النهج مناسبًا.

1. ثبّت CLI وسجّل الدخول 

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

يعيد كل أمر JSON منظمًا، وغالبًا يتضمن agentHints.nextSteps لاقتراح الخطوة التالية. استخدم --help مع أي مجموعة أوامر لمعرفة الخيارات المتاحة.

2. أنشئ نماذج البيانات

ابدأ بالمخططات القابلة لإعادة الاستخدام، مثل Order:

apidog schema --help
apidog schema create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

إذا كنت تملك مواصفة OpenAPI بالفعل، استوردها بدل إعادة إنشاء الموارد يدويًا:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

يدعم apidog import تنسيقات OpenAPI 3.x وSwagger 2.0 وPostman وApidog.

3. أضف نقاط النهاية

اعرض نقاط النهاية الحالية ثم أنشئ نقطة نهاية جديدة:

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

يمكنك استخدام JSON الناتج في scripts للمقارنة بين الفروع أو للتحقق من وجود المسارات والاستجابات المطلوبة. نظّم العمليات المتشابهة باستخدام folder.

4. عرّف المصادقة على مستوى المشروع

المصادقة جزء من العقد. استخدم security-scheme لتعريف مفاتيح API أو Bearer tokens أو OAuth 2.0:

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

عرّف المخطط الأمني مرة واحدة، ثم أشر إليه من نقاط النهاية. هذا يقلل تكرار الإعدادات وانجراف العقد بين العمليات.

5. تحقّق من ملفات موارد CLI

قبل تطبيق تعريف مورد في المشروع، تحقّق من بنيته:

apidog cli-schema --help
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

أضف هذا الأمر إلى CI قبل تنفيذ أي كتابة. تذكّر أن هذا يتحقق من بنية مورد CLI، وليس من أسلوب OpenAPI أو جودة العقد. استخدم Spectral للمهمة الثانية.

6. صدّر العقد إلى OpenAPI

يمكنك العودة إلى ملف OpenAPI محمول في أي وقت:

apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

بعد التصدير، مرّر الملف إلى Spectral أو openapi-generator أو نظام التوثيق الخاص بك.

اربط الخطوات بـ CI

اجعل كل مرحلة قابلة للفشل برمز خروج واضح:

# فشل عند وجود مخالفات في أسلوب OpenAPI
spectral lint openapi.yaml

# التحقق من صحة ملف مورد Apidog CLI
apidog cli-schema validate --file resource.json

# تجميع المواصفة في ملف واحد
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

# توليد هيكل الخادم
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

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

المشاكل الشائعة

الملفات المقسمة تعطل الأدوات اللاحقة

تقسيم المواصفة عبر $ref مفيد للقراءة، لكن بعض المولدات وأدوات النشر تحتاج ملفًا واحدًا. شغّل دائمًا:

redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

تتوقع من Apidog تنفيذ lint

Apidog يدير الموارد ولا يفرض قواعد أسلوب OpenAPI. احتفظ بـ Spectral أو vacuum في pipeline. كذلك، لا تخلط بين:

  • apidog cli-schema validate: يتحقق من بنية مورد CLI.
  • spectral lint: يتحقق من جودة واتساق مواصفة OpenAPI.

تعدّل مشروعًا فارغًا بدل استيراد العقد الحالي

إذا كانت API موجودة بالفعل، استورد المواصفة أولًا:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

تكرر إعدادات المصادقة في كل نقطة نهاية

عرّف security-scheme مرة واحدة على مستوى المشروع، ثم أشر إليه. التكرار هو أحد أسرع أسباب اختلاف سلوك المصادقة بين العمليات.

الخلاصة

تصميم API من الطرفية يحوّل سلسلة من النقرات اليدوية إلى أوامر قابلة للمراجعة والتشغيل في CI.

  • اختر المسار المفتوح المصدر إذا كنت تريد التحكم الكامل: OpenAPI، ثم Spectral، ثم Redocly، ثم openapi-generator.
  • اختر Apidog CLI إذا كنت تريد إدارة المخططات ونقاط النهاية والمصادقة ضمن مشروع متكامل من الطرفية.
  • اجمع بين المسارين عبر apidog export للحصول على ملف OpenAPI قابل للنقل.

إذا كنت تعمل بالفعل داخل Git وبأدوات مستقلة، حافظ على مسارك الحالي. وإذا كنت تريد تقليل صيانة الربط بين الأدوات، نزّل Apidog، وثبّت CLI، وابدأ تصميم واجهة API التالية دون مغادرة الطرفية.

Top comments (0)