DEV Community

Cover image for كيفية توثيق APIs باستخدام CLI
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية توثيق APIs باستخدام CLI

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

جرّب Apidog اليوم

لتشغيل التوثيق من الطرفية مزايا عملية واضحة: الأوامر قابلة للبرمجة والمراجعة في Git، ويمكن لمشغل CI أو وكيل ذكاء اصطناعي تنفيذها دون متصفح أو نقرات يدوية. لا توجد خطوة من نوع: «هل تذكرت الضغط على تصدير؟».

يغطي هذا الدليل مسارين:

  1. تحويل ملف OpenAPI إلى مرجع HTML مستقل أو Markdown بأمر واحد.
  2. استخدام Apidog CLI للتصدير من مشروع حي، بحيث يبقى مصدر الحقيقة والمخرجات متزامنين.

للمقارنة بين الأدوات، راجع قائمة أفضل 10 أدوات لتوثيق REST API وأدوات توثيق API المجانية.

للمتابعة، تحتاج إلى ملف OpenAPI 3.x، مثل:

openapi.yaml
Enter fullscreen mode Exit fullscreen mode

أو:

openapi.json
Enter fullscreen mode Exit fullscreen mode

بناء مرجع HTML باستخدام Redocly CLI

تُعد Redocly CLI طريقة مباشرة لتحويل وصف OpenAPI إلى صفحة HTML مستقلة. تستخدم الأداة Redoc وتضمّن الأنماط والسكربتات والمحتوى في ملف واحد يمكن استضافته في أي مكان.

1. ثبّت الأداة 

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

أو شغّلها عبر npx إذا لم ترغب في تثبيتها عالميًا.

2. أنشئ التوثيق 

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

ينشئ الأمر افتراضيًا ملفًا باسم:

redoc-static.html
Enter fullscreen mode Exit fullscreen mode

لفرض اسم أو مسار محدد للمخرج:

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

متى تستخدمه؟

استخدم Redocly CLI عندما تحتاج إلى:

  • مرجع API بصيغة HTML.
  • ملف مستقل يمكن استضافته أو مشاركته.
  • تدفق بسيط: ملف OpenAPI واحد ← أمر واحد ← ملف HTML واحد.

يدعم هذا المسار Swagger 2.0 وOpenAPI 3.0 وOpenAPI 3.1. لكنه يركز على المرجع الناتج من المواصفات؛ الأدلة الطويلة وصفحات البدء السريع تحتاج إلى إدارة منفصلة.

إنشاء Markdown باستخدام Widdershins

إذا كان موقع التوثيق أو المستودع لديك يعتمد على Markdown، فاستخدم Widdershins. تحوّل الأداة تعريفات OpenAPI وSwagger وAsyncAPI إلى Markdown متوافق مع Slate.

1. ثبّت Widdershins 

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

2. حوّل المواصفات إلى ملف Markdown 

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

إذا حذفت -o، ستطبع الأداة الناتج إلى stdout، ما يسمح بتوجيهه إلى أمر أو ملف آخر:

widdershins openapi.yaml > docs/api.md
Enter fullscreen mode Exit fullscreen mode

3. اضبط علامات تبويب لغات أمثلة الكود 

widdershins openapi.yaml \
  --language_tabs 'shell:cURL' 'python:Python' \
  -o api.md
Enter fullscreen mode Exit fullscreen mode

متى تستخدمه؟

Widdershins مناسب عندما تريد:

  • إضافة المرجع إلى مجلد docs/ في المستودع.
  • تمرير Markdown إلى مولد مواقع ثابتة.
  • تخصيص لغة أمثلة الطلبات في المرجع.

إذا كنت تبني تدفق تصدير Markdown أوسع، راجع دليل مولد مستندات API مع تصدير Markdown.

نقطة الضعف المشتركة بين Redocly وWiddershins هي أن كليهما يقرأ ملفًا ثابتًا. إذا كان openapi.yaml قديمًا مقارنةً بالمصدر الذي يحرره فريقك، فسيكون التوثيق قديمًا أيضًا.

التوثيق من مشروع حي باستخدام Apidog CLI

يوفر Apidog مع apidog-cli مسارًا متكاملًا: نقاط النهاية والمخططات والمستندات المكتوبة تعيش في مشروع واحد، ثم تصدّرها واجهة سطر الأوامر عند الطلب.

بهذا الأسلوب، يقرأ التصدير من نفس المشروع الذي يعدله فريقك، بدل الاعتماد على ملف محلي قد لا يكون محدثًا.

1. ثبّت واجهة سطر الأوامر 

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

لإعداد Node وPATH، راجع دليل تثبيت Apidog CLI.

2. سجّل الدخول باستخدام رمز وصول 

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

يُخزّن الرمز على الجهاز، لذا لن تحتاج إلى تمريره مع كل استدعاء محليًا. في CI، يجب تنفيذ تسجيل الدخول ضمن كل مهمة جديدة.

بعد ذلك، تعمل الأوامر باستخدام معرّف المشروع. قبل تنفيذ أي أمر، استخدم --help للتحقق من العلامات المتاحة في إصدارك:

apidog --help
Enter fullscreen mode Exit fullscreen mode

استيراد مواصفات إلى المشروع

إذا كانت واجهة برمجة التطبيقات لديك موجودة في ملف OpenAPI، استوردها إلى مشروع Apidog:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

يدعم apidog import تنسيقات OpenAPI 3.x وSwagger 2.0 وPostman وApidog. بعد الاستيراد، يصبح المشروع هو المصدر الحي الذي تصدّر منه المستندات.

تصدير مستندات قابلة للقراءة

ابدأ بعرض خيارات التصدير المتاحة:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

ثم صدّر توثيق المشروع إلى Markdown:

apidog export --project <projectId> --format markdown --output ./api-docs.md
Enter fullscreen mode Exit fullscreen mode

لإنشاء HTML بدلًا من Markdown:

apidog export --project <projectId> --format html --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

ولتصدير مواصفات OpenAPI قابلة للنقل:

apidog export --project <projectId> --format openapi --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

إذا كان المشروع يحتوي على عدة خدمات، راجع خرج apidog export --help لمعرفة علامات تحديد النطاق والمعرّفات المتاحة في إصدار CLI لديك.

إدارة الأدلة المكتوبة

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

ابدأ بعرض الأوامر والمستندات الحالية:

apidog doc --help
apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

عند تنفيذ أوامر تعتمد على JSON، اقرأ الناتج واتبع agentHints.nextSteps إن ظهر. للتحقق من مخططات JSON قبل الإرسال، راجع:

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

هذا يساعدك على اكتشاف الحقول الناقصة محليًا قبل فشل الطلب في CI أو أثناء التنفيذ.

نشر موقع توثيق

لإدارة التوثيق المنشور من الطرفية، راجع أوامر الموقع والروابط القابلة للمشاركة:

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

الفرق بين الأوامر مهم:

  • doc: مستند Markdown داخل شجرة مستندات المشروع.
  • docs-site: إدارة موقع التوثيق العام المستضاف.
  • shared-doc: إدارة روابط التوثيق القابلة للمشاركة.

استخدم docs-site عندما تريد إدارة موقع توثيق عام من سطر الأوامر، واستخدم shared-doc عندما تحتاج إلى رابط لمشاركته مع شريك أو فريق.

ربط إنشاء التوثيق بـ CI

بعد نجاح الأوامر محليًا، أضفها إلى مسار العمل. المثال التالي يعيد إنشاء مرجع Markdown باستخدام GitHub Actions:

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

يمكنك تطبيق الفكرة نفسها مع Redocly:

- name: Build HTML API docs
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

أو مع Widdershins:

- name: Generate Markdown API docs
  run: |
    npm install -g widdershins
    widdershins openapi.yaml -o docs/api.md
Enter fullscreen mode Exit fullscreen mode

بهذا تتحول المستندات من مهمة يدوية إلى ناتج بناء قابل لإعادة الإنشاء عند كل تغيير.

للتفاصيل، راجع الدليل الكامل لـ Apidog CLI.

عقبات شائعة

معرّف المشروع خاطئ أو مفقود

تحتاج أوامر Apidog مثل export وdoc وdocs-site إلى:

--project <projectId>
Enter fullscreen mode Exit fullscreen mode

استخدم معرّف المشروع الفعلي من إعدادات المشروع، وليس الاسم المقروء بشريًا.

الرمز غير متاح في CI

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

apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

احفظ الرمز كـ secret، ولا تضعه في ملف workflow.

ملف OpenAPI قديم

يقرأ Redocly وWiddershins الملف الذي تمرره إليهما. إذا كان openapi.yaml قديمًا، ستكون المستندات قديمة. لتجنب هذا الانحراف، صدّر من مشروع حي عند استخدام Apidog CLI.

التخمين في العلامات

قد تختلف علامات export وdoc وdocs-site وshared-doc بين إصدارات CLI. لا تعتمد على علامة تتذكرها جزئيًا؛ تحقق دائمًا من المساعدة:

apidog <command> --help
Enter fullscreen mode Exit fullscreen mode

الخلاصة

اختر الأداة وفقًا للمخرج الذي تحتاجه:

  • استخدم Redocly CLI لمرجع HTML مستقل.
  • استخدم Widdershins لمرجع Markdown يمكن دمجه في موقع توثيق أو مستودع.
  • استخدم Apidog CLI عندما تريد تصدير المرجع والأدلة المكتوبة وإدارة موقع توثيق من مشروع حي واحد.

جميع الأوامر قابلة للبرمجة، لذا أضفها إلى CI مرة واحدة واجعل التوثيق يُعاد إنشاؤه تلقائيًا مع كل تغيير.

نزّل Apidog لتجربة واجهة سطر الأوامر، أو تعرّف أكثر على كيفية عمل Apidog ضمن سير عمل يعتمد على API أولًا.

Top comments (0)