DEV Community

Cover image for أدوات سطر الأوامر مجانية ومفتوحة المصدر لتوثيق الـ API
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

أدوات سطر الأوامر مجانية ومفتوحة المصدر لتوثيق الـ API

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

جرّب Apidog اليوم

هذه القائمة تركز على أدوات CLI مفتوحة المصدر تعمل مباشرةً مع ملفات OpenAPI أو Swagger. يمكنها إنتاج Markdown أو HTML ثابت أو موقع وثائق كامل تستضيفه بنفسك. جميع الأدوات المذكورة متاحة على GitHub بترخيص MIT أو Apache 2.0، ولا تحتاج إلى حساب لتشغيلها.

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

ملاحظة: يظهر Apidog قرب نهاية المقال كملاحظة جانبية فقط. ليس مفتوح المصدر؛ بل منصة تجارية بنموذج فريميوم. الغرض من ذكره هو توضيح الفجوة بين تصدير ملف مواصفات ثابت وإدارة مشروع API حي.

ما الذي يجعل أداة توثيق CLI مفتوحة المصدر؟

لا تعني «مفتوحة المصدر» أنها مجانية للتنزيل فقط. عند دمج الأداة في عملية البناء، تحقق من هذه النقاط:

  1. ترخيص متساهل فعليًا

    يتيح MIT وApache 2.0 استخدام الأداة وتعديلها وإعادة توزيعها تجاريًا. يضيف Apache 2.0 منحًا صريحًا لبراءات الاختراع، وهو ما قد تفضله بعض الفرق القانونية.

  2. مخرجات قابلة للاستضافة الذاتية

    يجب أن تنتج الأداة ملفات تملكها: Markdown، أو ملف HTML واحد، أو مجلد HTML/CSS/JS. عندها يمكنك النشر على GitHub Pages أو S3 أو Nginx بدون الاعتماد على خوادم بائع.

  3. صيانة ومجتمع

    تحقق من النشاط الأخير، والقضايا المفتوحة، والتفرعات النشطة. بعض الأدوات المؤرشفة ما زالت تعمل، لكنها قد تتطلب منك صيانة تفرع خاص بك لاحقًا.

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

Redocly CLI

Redocly CLI هو مسار سريع لتحويل مواصفات OpenAPI إلى مرجع HTML مصقول ومكتفٍ ذاتيًا. سطر الأوامر ومحرك عرض Redoc مفتوحان المصدر بترخيص MIT، بينما تبقى بعض ميزات البوابة المستضافة ضمن المنتج المدفوع.

أنشئ ملف HTML واحدًا من المواصفات:

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

ثم اختبر الناتج محليًا:

open api-docs.html
Enter fullscreen mode Exit fullscreen mode

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

Redocly CLI

استخدمه عندما: تريد مرجع API نظيفًا من صفحة واحدة بأقل إعداد ممكن.

انتبه إلى: الناتج صفحة واحدة، وليس بوابة وثائق متعددة الصفحات. إذا كنت تقارن محركات العرض، راجع بدائل Redocly.

Widdershins

Widdershins محول بترخيص MIT يحول OpenAPI 3 وSwagger 2 وAsyncAPI إلى Markdown. لا يقدم موقعًا جاهزًا؛ بل يمنحك ملفات Markdown تستطيع تثبيتها في Git، ومراجعتها في pull requests، وتمريرها إلى أي مولد مواقع ثابت.

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

لضبط الناتج:

widdershins openapi.yaml \
  --omitHeader \
  --language_tabs 'javascript:JavaScript' 'python:Python' \
  -o api-docs.md
Enter fullscreen mode Exit fullscreen mode
  • --omitHeader: يحذف القسم التمهيدي.
  • --language_tabs: يحدد لغات أمثلة الكود.

Widdershins

استخدمه عندما: تريد Markdown قابلًا للتحكم في الإصدارات أو تريد تغذية Slate أو Docusaurus أو مولد موقع آخر.

انتبه إلى: Markdown هو الناتج النهائي؛ ستحتاج إلى أداة أخرى لتحويله إلى موقع معروض.

OpenAPI Generator

OpenAPI Generator مشروع مجتمعي بترخيص Apache 2.0، تفرع من Swagger Codegen في 2018. يشتهر بتوليد SDKs، لكنه يوفر أيضًا مولدات للوثائق.

ثبّت الواجهة ثم أنشئ Markdown أو HTML:

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

# مجلد يحتوي ملفات Markdown
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# صفحة HTML مستقلة
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Enter fullscreen mode Exit fullscreen mode

يمكنك وضع هذه الأوامر في CI، ثم نشر المجلد الناتج كأحد مخرجات البناء:

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

OpenAPI Generator

استخدمه عندما: تريد أداة واحدة لتوليد SDKs والوثائق من نفس مواصفات OpenAPI.

انتبه إلى: غلاف npm ينزّل ملف Java JAR في التشغيل الأول، لذا ليس أداة ثنائية خفيفة بالكامل. مخرجات القوالب أساسية مقارنةً بمحركات العرض المتخصصة.

Swagger Codegen

Swagger Codegen هو المولد الأصلي من فريق Swagger، بترخيص Apache 2.0، وما زال يُصان بواسطة SmartBear. يوفّر مولد html لمرجع ثابت من صفحة واحدة، وdynamic-html لموقع تفاعلي صغير.

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/
Enter fullscreen mode Exit fullscreen mode

إذا كان فريقك يستخدم Swagger Codegen بالفعل لتوليد المكونات أو العملاء، فإن استخدامه للوثائق يحافظ على سلسلة أدوات موحدة.

Swagger Codegen

استخدمه عندما: يكون نظام Swagger البيئي جزءًا من إعدادك الحالي.

انتبه إلى: يعتمد على Java ويتطور بوتيرة أبطأ من OpenAPI Generator. للإعدادات الجديدة، يكون OpenAPI Generator غالبًا الخيار الأكثر نشاطًا؛ بينما يتفوق Swagger Codegen في الاستمرارية للفرق التي اعتمدته مسبقًا.

Docusaurus مع إضافة OpenAPI

إذا كنت تحتاج إلى بوابة وثائق كاملة بدل صفحة HTML واحدة، فاستخدم Docusaurus بترخيص MIT. يعرض Docusaurus ملفات Markdown وMDX، بينما تحول إضافة docusaurus-openapi-docs مواصفات OpenAPI إلى صفحات MDX داخل الموقع.

ابدأ مشروعًا جديدًا:

npx create-docusaurus@latest my-docs classic
cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
Enter fullscreen mode Exit fullscreen mode

بعد إعداد الإضافة ومسار ملف المواصفات، ولّد صفحات API:

npm run docusaurus gen-api-docs all
npm run build
Enter fullscreen mode Exit fullscreen mode

ينتج build موقعًا ثابتًا في مجلد build/ يمكنك نشره على GitHub Pages أو S3 أو أي CDN.

Docusaurus OpenAPI

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

انتبه إلى: هذا هو الإعداد الأثقل في القائمة؛ فهو موقع React كامل مع خطوة بناء. إذا كنت تحتاج فقط إلى مرجع API، فـ Redocly CLI أقصر بكثير.

Slate

Slate هو تخطيط وثائق API الكلاسيكي بثلاثة أعمدة: تنقل على اليسار، محتوى في الوسط، وأمثلة كود على اليمين. يعمل بترخيص Apache 2.0 ويستخدم Middleman، لذلك يحتاج إلى Ruby وBundler.

لا يقرأ Slate مواصفات OpenAPI مباشرةً. بدلاً من ذلك، تكتب Markdown يدويًا أو تولده باستخدام Widdershins، ثم تبني الموقع:

# بعد استنساخ تفرع Slate وتشغيل bundle install
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

سيظهر الموقع الثابت في مجلد:

build/
Enter fullscreen mode Exit fullscreen mode

مسار عملي شائع:

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

استخدمه عندما: تريد وثائق سردية منتقاة يدويًا وتحكمًا تحريريًا كاملًا بتخطيط ثلاثي الأعمدة.

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

Apidog CLI: ملاحظة جانبية، وليس إدخالًا مفتوح المصدر

الأدوات السابقة تغطي التحويل أو العرض أو الاستضافة. لكن عند التعامل مع مشروع API حي يحتوي على نقاط نهاية ومخططات وأمثلة تُحدَّث باستمرار، قد تحتاج إلى ربط محول وعارض واستضافة بنفسك والحفاظ على تزامنها.

Apidog CLI

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

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

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

يمكنك استخدام التصدير ضمن CI لإعادة بناء الوثائق عند تحديث المشروع. كما يوفر apidog doc وapidog docs-site إدارة موارد الوثائق من خلال سكربتات.

للتفاصيل، راجع الدليل الكامل لـ Apidog CLI ومولد وثائق API مع تصدير Markdown.

الحد الفاصل بسيط:

  • الأدوات المفتوحة: كود تملكه، ملفات تستضيفها، ولا تبعية لبائع.
  • Apidog: مسار متكامل من مشروع مُدار إلى وثائق قابلة للمشاركة، لكنه منتج مستضاف بنموذج فريميوم.

كيف تختار

طابق الأداة مع نوع المخرجات التي تحتاجها وسير العمل الحالي لفريقك:

الأداة الأفضل لـ التثبيت مفتوحة المصدر؟ المخرجات
Redocly CLI صفحة HTML مصقولة واحدة npx @redocly/cli نعم، MIT HTML مستقل
Widdershins تحويل المواصفات إلى Markdown قابل للتثبيت npm i -g widdershins نعم، MIT Markdown
OpenAPI Generator وثائق وSDKs من أداة واحدة npm i -g @openapitools/openapi-generator-cli نعم، Apache 2.0 Markdown أو HTML
Swagger Codegen فرق تعتمد Swagger Codegen مسبقًا npm i -g swagger-codegen-cli نعم، Apache 2.0 HTML
Docusaurus + OpenAPI plugin بوابة وثائق كاملة مستضافة ذاتيًا npx create-docusaurus نعم، MIT موقع ثابت
Slate وثائق منتقاة يدويًا بثلاثة أعمدة Ruby + Bundler نعم، Apache 2.0 موقع ثابت
Apidog CLI التصدير من مشروع API حي npm i -g apidog-cli لا، فريميوم Markdown أو HTML

اختيار سريع:

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

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

خلاصة

يعتمد اختيار أداة توثيق CLI مفتوحة المصدر على ثلاثة عوامل: الترخيص، نوع المخرجات، ومكان وجود مصدر الحقيقة لواجهة API.

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

  • Redocly CLI لصفحة HTML واحدة.
  • Widdershins لـ Markdown.
  • OpenAPI Generator أو Swagger Codegen للوثائق بجانب SDKs.
  • Docusaurus لبوابة وثائق.
  • Slate للصفحات المنتقاة يدويًا.

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

Top comments (0)