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

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

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

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

إذا كنت تتابع باستخدام Apidog، فاحصل على الملف التنفيذي أولاً. يغطي دليل تثبيت Apidog CLI خطوة npm install -g apidog-cli والمصافحة apidog login --with-token، والدليل الكامل لـ Apidog CLI يحدد كل مجموعة أوامر.

المسار العام مفتوح المصدر: التأليف، التنظيم (lint)، التجميع (bundle)، التوليد (generate)

تُعد حزمة تصميم سطر الأوامر (CLI) الكلاسيكية مجموعة من الأدوات المستقلة التي تربطها ببعضها. تحتفظ بتعريف واجهة برمجة التطبيقات الخاصة بك في ملف OpenAPI تحت التحكم في الإصدار، وتشغل كل أداة كخطوة. هذا هو سير عمل تصميم واجهة برمجة التطبيقات الأصيل لـ Git، وهو جيد حقًا. إليك شكله.

تأليف مستند OpenAPI

تبدأ بملف YAML عادي. لا يتطلب الأمر محررًا خاصًا؛ أي محرر نصوص يعمل. يبدو ملف 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]

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

التنظيم (Lint) باستخدام Spectral

ينجرف ملف OpenAPI المكتوب يدويًا. ينسى شخص ما operationId، ويترك شخص آخر استجابة غير موثقة، ويخترع شخص ثالث اتفاقية تسمية خاصة به. يكتشف المدقق اللغوي كل ذلك قبل المراجعة. Spectral، من Stoplight، هو الخيار القياسي. يأتي مع مجموعات قواعد لـ OpenAPI ويتيح لك كتابة قواعدك الخاصة.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

يطبع Spectral كل انتهاك مع رقم السطر وشدة الخطأ. يمكنك إفشال البناء في حالة وجود أخطاء عن طريق التحقق من رمز الخروج في CI. يقوم Redocly's CLI وvacuum بنفس المهمة إذا كنت تريد بديلاً؛ vacuum سريع ويعمل كمدقق لغوي متوافق مع Spectral. النقطة قائمة بغض النظر عن أي واحد تختاره: التنظيم هو أداة منفصلة ومخصصة، وتقوم بتشغيلها كخطوة مستقلة.

التجميع (Bundle) باستخدام Redocly CLI

بمجرد تقسيم تعريفك عبر الملفات، ترغب معظم الأدوات اللاحقة في مستند واحد مكتمل بذاته. يحل Redocly CLI كل $ref ويسوي الشجرة في ملف واحد.

npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

يقوم Redocly أيضًا بالتدقيق (redocly lint) ومعاينة المستندات، لذا تستخدمه بعض الفرق لكل من التحقق من الأنماط والتجميع. تسرد وثائقه الرسمية مجموعة الأوامر الكاملة.

توليد القوالب باستخدام openapi-generator

باستخدام مواصفات نظيفة ومجمعة، يمكنك توليد الكود. يحول openapi-generator مستند OpenAPI إلى قوالب خادم، وحزم SDK للعميل، وغير ذلك الكثير عبر عشرات اللغات.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server

استبدل -g spring بـ -g python-flask، أو -g go-server، أو أي من المولدات المدعومة. الآن لديك هيكل يتطابق مع عقدك تمامًا.

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

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

يحتفظ النهج الآخر بالتصميم والمخططات ونقاط النهاية والمحاكاة والمصادقة داخل مشروع واحد تديره من الطرفية. الملف التنفيذي apidog-cli هو واجهة سطر أوامر (CLI) كاملة لموارد المشروع، وليس مجرد مشغل اختبار. لديه مجموعات أوامر لسطح التصميم بأكمله: schema لنماذج البيانات، endpoint للعمليات، folder للتنظيم، security-scheme للمصادقة، بالإضافة إلى import، export، mock، والمزيد.

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

قم بالتثبيت والمصادقة أولاً (راجع دليل التثبيت لإعداد الرمز المميز):

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

يعيد كل أمر JSON منظمًا، وتتضمن معظم الاستجابات كتلة agentHints.nextSteps تخبرك (أو وكيلًا) بما يجب تشغيله بعد ذلك. أضف --help إلى أي أمر لرؤية علاماته الدقيقة.

تعريف نماذج البيانات باستخدام مخطط apidog

يبدأ التصميم ببياناتك. يصبح مخطط Order القابل لإعادة الاستخدام مصدر الحقيقة الوحيد الذي تشير إليه نقاط النهاية، وهي نفس فكرة components/schemas في OpenAPI الخام، ولكن تتم إدارته كمورد للمشروع.

apidog schema --help
apidog schema create --project <PROJECT_ID>

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

apidog import --project <PROJECT_ID> --file openapi.yaml

يقبل apidog import تنسيقات OpenAPI 3.x، وSwagger 2.0، وPostman، وApidog، لذا يصبح التعريف الموجود مشروعًا حيًا في خطوة واحدة.

تعريف نقاط النهاية باستخدام apidog endpoint

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

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>

سرد نقاط النهاية كـ JSON مفيد بحد ذاته. يمكنك مقارنة الإخراج عبر الفروع أو تغذيته لبرنامج نصي يتحقق من أن كل مسار يحتوي على الاستجابات التي تتوقعها. قم بتجميع نقاط النهاية ذات الصلة باستخدام أمر folder بحيث يظل المشروع سهل التصفح مع نموه.

تعريف المصادقة باستخدام apidog security-scheme

المصادقة جزء من العقد، وليست فكرة لاحقة. تحدد مجموعة security-scheme كيفية مصادقة العملاء: مفاتيح API، ورموز الحامل (bearer tokens)، وOAuth 2.0، وما إلى ذلك. هذا يتطابق مع components/securitySchemes في OpenAPI، لذا فإن الاستيراد والتصدير يتمان بسلاسة.

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>

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

التحقق من صحة كتاباتك باستخدام apidog cli-schema validate

قبل أن تلتزم بالتغييرات أو تسلم مشروعًا إلى CI، تريد أن تعرف أن تعريفات مواردك جيدة التكوين. تأتي CLI بأمر cli-schema validate يتحقق من ملف التعريف مقابل المخطط الذي تتوقعه CLI، بحيث يفشل الكتابة سيئة التكوين بسرعة بدلاً من أن تتم دون علم.

apidog cli-schema --help
apidog cli-schema validate --file resource.json

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

التصدير مرة أخرى إلى OpenAPI

صمم في Apidog، ثم سلم أثرًا قياسيًا إلى بقية سلسلة أدواتك. يكتب apidog export ملفات OpenAPI، HTML، Markdown، أو Postman.

apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml

الآن عدت إلى ملف OpenAPI محمول. قم بتغذيته إلى Spectral للتدقيق اللغوي، أو إلى openapi-generator للقوالب، أو إلى بناء وثائقك. المشروع المتكامل ومكدس الأدوات المفتوحة ليسا حصريين لبعضهما البعض؛ التصدير هو الجسر بينهما.

ربطه بـ CI (التكامل المستمر)

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

# فشل في حالة وجود انتهاكات للأسلوب
spectral lint openapi.yaml

# التحقق من صحة أي كتابات لموارد CLI قبل تطبيقها
apidog cli-schema validate --file resource.json

# تسطيح إلى أثر واحد للخطوات اللاحقة
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml

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

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

تؤدي الملفات المقسمة إلى تعطيل الأدوات اللاحقة. يعد التعريف الموزع عبر العديد من ملفات $ref رائعًا للبشر ومحرجًا للمولدات. دائمًا ما قم بتجميعها في ملف واحد قبل إنشاء الكود أو نشر المستندات. redocly bundle هو الحل.

تتوقع أن يقوم Apidog بالتدقيق (lint). لن يفعل. يدير Apidog الموارد؛ ولا يفرض دليل أسلوب أو يبلغ عن انتهاكات قواعد OpenAPI. احتفظ بـ Spectral أو vacuum في الحلقة لذلك. يعد الخلط الشائع هو اعتبار apidog cli-schema validate كمدقق لغوي؛ فهو يتحقق من بنية المورد، وليس أسلوب OpenAPI.

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

المصادقة المعرفة لكل نقطة نهاية بدلاً من مرة واحدة. حدد security-scheme على مستوى المشروع وارجع إليه. إعادة الإعلان عن المصادقة في كل عملية هي كيفية انجراف العقود.

الخلاصة

يُحوّل تصميم واجهات برمجة التطبيقات من سطر الأوامر مهمة تتطلب الكثير من النقرات إلى مجموعة من الأوامر المتكررة. يمنحك المسار المفتوح، تأليف، تدقيق باستخدام Spectral، تجميع باستخدام Redocly، توليد باستخدام openapi-generator، تحكمًا كاملاً وعدم تقيد. يمنحك مسار Apidog CLI مشروعًا متكاملًا حيث تعيش المخططات ونقاط النهاية والمصادقة معًا وتعيد كل أمر JSON جاهزًا للوكيل. يربط التصدير بين المسارين، لذا لن تتعثر أبدًا.

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