DEV Community

Cover image for أفضل أدوات سطر الأوامر خفيفة الوزن لتوثيق الـ API
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

أفضل أدوات سطر الأوامر خفيفة الوزن لتوثيق الـ API

لديك ملف OpenAPI وتريد توليد مستندات منه بدون إعداد خدمة، أو تسجيل الدخول إلى بوابة، أو إضافة خطوة بناء تسحب نصف حزمة npm. المطلوب بسيط: أمر واحد يقرأ المواصفات وينتج ملف Markdown أو صفحة HTML مستقلة يمكنك استضافتها في أي مكان.

جرّب Apidog اليوم

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

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

ما الذي يجعل أداة سطر الأوامر خفيفة الوزن؟

الأداة خفيفة الوزن عندما تقلل الاحتكاك بين ملف المواصفات وملف الوثائق النهائي:

  • تثبيت صغير: حزمة واحدة أو ثنائي واحد أفضل من سلسلة أدوات كاملة.
  • إعداد محدود: يجب أن تتمكن من تمرير openapi.yaml مباشرةً دون ملف إعدادات إضافي.
  • مخرج واضح: مواصفات في الداخل، وMarkdown أو HTML في الخارج.
  • قابلة للتشغيل في CI: لا واجهة رسومية، ولا خادم دائم، ولا تسجيل دخول للأدوات المفتوحة المصدر.

لخيارات أوسع تشمل منصات مستضافة، راجع أدوات توثيق واجهة برمجة التطبيقات المجانية.

Widdershins

يحول Widdershins ملفات OpenAPI 3 وSwagger 2 وAsyncAPI إلى Markdown. استخدمه عندما تريد ملفًا نصيًا قابلًا للحفظ في Git، أو المراجعة في Pull Request، أو إدراجه في موقع وثائق قائم.

التثبيت والتشغيل 

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

لإنشاء الملف داخل خطوة CI:

widdershins openapi.yaml \
  --omitHeader \
  --language_tabs 'shell:curl' 'javascript:JavaScript' \
  -o docs/api.md
Enter fullscreen mode Exit fullscreen mode
  • --omitHeader: يحذف مقدمة YAML من المخرج.
  • --language_tabs: يحدد لغات أمثلة الكود.

متى تستخدمه؟

استخدم Widdershins إذا كنت تحتاج إلى Markdown فقط وتخطط لعرضه لاحقًا عبر مولد موقع ثابت أو منصة وثائق.

القيود: لا ينشئ موقعًا أو واجهة تفاعلية. إنه محول مواصفات إلى Markdown، وليس عارض وثائق.

OpenAPI Generator

تشتهر OpenAPI Generator بتوليد حزم SDK، لكنها تتضمن أيضًا مولدات للوثائق. استخدمها إذا كنت تولد SDK ووثائق من نفس مواصفات OpenAPI.

التثبيت 

npm install -g @openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

توليد Markdown 

openapi-generator-cli generate \
  -g markdown \
  -i openapi.yaml \
  -o docs/
Enter fullscreen mode Exit fullscreen mode

توليد HTML مستقل 

openapi-generator-cli generate \
  -g html2 \
  -i openapi.yaml \
  -o docs-html/
Enter fullscreen mode Exit fullscreen mode

يمكنك إضافته إلى package.json:

{
  "scripts": {
    "docs:markdown": "openapi-generator-cli generate -g markdown -i openapi.yaml -o docs",
    "docs:html": "openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html"
  }
}
Enter fullscreen mode Exit fullscreen mode

ملاحظة عملية: غلاف npm ينزّل ملف JAR يعمل عبر JDK عند أول تشغيل، لذلك قد يكون أثقل من Widdershins في بيئة CI نظيفة.

Redocly CLI: إنشاء HTML بأمر واحد

إذا كان هدفك صفحة مرجعية HTML مستقلة، فإن Redocly CLI يوفر مسارًا مباشرًا. يبني build-docs ملف HTML واحدًا مبنيًا على Redoc، دون تشغيل خادم.

إنشاء الملف الافتراضي 

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

ينتج الأمر افتراضيًا الملف:

redoc-static.html
Enter fullscreen mode Exit fullscreen mode

تحديد اسم ملف الإخراج 

npx @redocly/cli build-docs openapi.yaml --output api.html
Enter fullscreen mode Exit fullscreen mode

مثال مناسب لخط CI:

npx @redocly/cli build-docs openapi.yaml --output public/api.html
Enter fullscreen mode Exit fullscreen mode

بعد ذلك، انشر محتوى public/ على أي استضافة ثابتة.

الأفضل لـ: صفحة مرجعية مصقولة وقابلة للمشاركة بسرعة.

القيود: المخرج صفحة HTML واحدة، وليس بوابة وثائق متعددة الصفحات. لمقارنة البدائل، راجع بدائل Redocly وبدائل Scalar.

Slate

Slate ليس محول OpenAPI مباشرًا؛ إنه مولد موقع ثابت لوثائق API المكتوبة يدويًا باستخدام Markdown. ينشئ التصميم التقليدي ذي الأعمدة الثلاثة: التنقل والمحتوى وعينات الكود.

يعمل Slate عبر Ruby وMiddleman، لذا فهو يحتاج إلى سلسلة أدوات أكبر من الخيارات الأخرى.

# بعد استنساخ مستودع Slate وتثبيت التبعيات
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

ينشئ الأمر موقعًا ثابتًا داخل:

build/
Enter fullscreen mode Exit fullscreen mode

دمج Slate مع Widdershins

يمكنك استخدام الأداتين معًا:

widdershins openapi.yaml -o source/includes/_api.md
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

بهذا تحصل على محتوى Markdown مولّد من OpenAPI ضمن قالب Slate.

الأفضل لـ: فرق تريد تحرير الشرح والبنية يدويًا، مع الاستفادة من مواصفات OpenAPI كنقطة بداية.

القيود: يحتاج Ruby، ولا يقرأ OpenAPI وحده.

Apidog CLI: التصدير من مشروع API

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

يوفر apidog-cli أوامر للتعامل مع مشروع Apidog وتصدير مستنداته إلى Markdown أو HTML.

التثبيت والمصادقة 

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

تصدير Markdown 

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

تصدير HTML 

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

إدارة موارد الوثائق 

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

تعيد هذه الأوامر مخرجات JSON منظمة، لذلك يمكن تمريرها إلى خطوة أخرى في CI أو إلى نص برمجي.

مثال مبسط في CI:

apidog login --with-token "$APIDOG_TOKEN"

apidog export \
  --project "$APIDOG_PROJECT_ID" \
  --format html \
  --output ./public/api.html
Enter fullscreen mode Exit fullscreen mode

للتفاصيل الكاملة حول المصادقة والمشاريع والأوامر، راجع الدليل الكامل لـ Apidog CLI.

تنبيه مهم: Apidog ليس مفتوح المصدر، وCLI يتصل بمشروع مستضاف. كما أنه لا يحل محل أدوات فحص OpenAPI أو فرض دليل الأسلوب مثل Redocly وSpectral. قيمته الأساسية هي توفير مسار موحد من مشروع API إلى Markdown أو HTML قابل للنشر.

لمسار Markdown بشكل أكثر تفصيلًا، راجع مولد وثائق API مع تصدير Markdown.

كيف تختار؟

اختر وفقًا لشكل المدخلات والمخرج المطلوب:

الأداة الأفضل لـ التثبيت مفتوحة المصدر؟ المخرجات
Widdershins تحويل المواصفات إلى Markdown بسرعة npm i -g widdershins نعم، MIT Markdown
OpenAPI Generator وثائق إلى جانب حزم SDK npm i -g @openapitools/openapi-generator-cli نعم، Apache 2.0 Markdown أو HTML
Redocly CLI صفحة HTML مصقولة واحدة npx @redocly/cli نعم، MIT وopen core HTML مستقل
Slate موقع وثائق منسق يدويًا Ruby + Bundler نعم، Apache 2.0 موقع ثابت
Apidog CLI التصدير من مشروع مباشر npm i -g apidog-cli لا، طبقة مجانية Markdown أو HTML

اختيار سريع

  • لديك ملف OpenAPI وتريد Markdown: استخدم Widdershins.
  • تريد صفحة HTML واحدة للنشر أو المشاركة: استخدم Redocly CLI.
  • تولد SDK بالفعل وتريد الوثائق من الأداة نفسها: استخدم OpenAPI Generator.
  • تريد تحرير المستندات يدويًا ضمن تصميم ثابت: استخدم Slate.
  • تعمل من مشروع API وتحتاج إلى التصدير وإدارة الوثائق: استخدم Apidog CLI.

للقائمة الأوسع من الخيارات المجانية، راجع أدوات توثيق API المجانية.

الخلاصة

اختر أصغر أداة تنتج المخرج الذي تحتاجه:

  • يغطي Widdershins معظم حالات توليد Markdown من مواصفات OpenAPI.
  • يغطي redocly build-docs معظم حالات إنشاء HTML مستقل بأمر واحد.
  • استخدم OpenAPI Generator إذا كان موجودًا أصلًا في خط توليد SDK.
  • استخدم Slate عندما تكون الكتابة والتحرير اليدويان جزءًا أساسيًا من الوثائق.
  • استخدم apidog-cli عندما تكون واجهة برمجة التطبيقات موجودة في مشروع وتريد تصدير Markdown أو HTML دون ربط عدة أدوات يدويًا.

إذا كانت واجهة برمجة التطبيقات لديك موجودة في مشروع Apidog، نزّل Apidog ثم شغّل apidog export ضمن CI لإعادة بناء الوثائق عند كل تغيير في الـ API.

Top comments (0)