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

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

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

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

ما الذي يجعل أداة سطر الأوامر "خفيفة الوزن" لتوثيق واجهات برمجة التطبيقات؟

خفة الوزن لا تعني ضعف الأداء. بل تتعلق بحجم الأثر والاحتكاك. وهناك أربعة عوامل تحدد ذلك.

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

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

مخرجات ذات غرض واحد. كل أداة أدناه تقوم بشيء واحد: مواصفات داخل، وثائق خارج. Markdown أو HTML، لا شيء آخر ملحق. هذا ما يجعلها سريعة ويمكن التنبؤ بها في خط الأنابيب.

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

الآن، الأدوات، بدءًا من الأصغر.

Widdershins

Widdershins هو الأصغر قدر الإمكان. إنها حزمة npm واحدة تحول ملف OpenAPI 3 أو Swagger 2 أو AsyncAPI إلى Markdown. هذا هو كل عملها. لا تقوم بتقديم موقع أو تشغيل خادم؛ إنها تسلمك ملف .md وتخرج من الطريق.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

ملف Markdown الذي تنتجه متوافق مع Slate، وهو أمر مهم إذا كنت تخطط لتغذيته إلى موقع ثابت لاحقًا. الأعلام المفيدة: --omitHeader تحذف مقدمة YAML، و --language_tabs تتحكم في لغات عينات الكود التي تظهر.

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

OpenAPI Generator (مولدات الوثائق)

OpenAPI Generator معروفة بشكل أفضل لإنشاء حزم SDK للعملاء، لكنها تأتي أيضًا بمولدات وثائق، وهي مفيدة عندما تكون المواصفات هي كل ما لديك. يقوم المولد markdown بكتابة مجلد من ملفات Markdown؛ ويقوم المولد html2 بكتابة صفحة HTML واحدة مستقلة بذاتها. يمكنك تشغيلها من خلال غلاف npm دون الحاجة إلى تثبيت Java بنفسك.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

لا يزال غلاف npm يقوم بتنزيل ملف jar مدعوم بـ JDK تحت الغطاء، لذا فهو أثقل من Widdershins عند التشغيل الأول. بعد ذلك، يكون أمرًا واحدًا للتوليد.

الأفضل في: إعادة استخدام أداة قد تقوم بتشغيلها بالفعل لحزم SDK لتصدر وثائق أيضًا، مع خيار بين Markdown و HTML المستقل. القيود الصادقة: المخرجات بسيطة وتعتمد على القوالب، والاستدعاء الأول يسحب ملف jar، لذا فهي ليست ثنائية حقيقية أحادية. إذا كنت تحتاج فقط إلى الوثائق ولا شيء آخر، توجد خيارات أخف.

Redocly CLI (build-docs)

إذا كنت تريد صفحة HTML جميلة المظهر ومستقلة من أمر واحد، فإن Redocly CLI هو أقصر طريق. يقوم الأمر build-docs بتجميع مواصفاتك في ملف HTML واحد مستقل بذاته مبني على Redoc. لا يوجد خادم، لا بناء استضافة منفصل؛ تحصل على ملف يمكنك فتحه، أو إرساله عبر البريد الإلكتروني، أو وضعه على أي مضيف ثابت.

npx @redocly/cli build-docs openapi.yaml

افتراضيًا، يكتب redoc-static.html. قم بتغيير الاسم باستخدام --output:

npx @redocly/cli build-docs openapi.yaml --output api.html

لأنه يعمل من خلال npx، لا تحتاج حتى إلى تثبيته عالميًا لتجربته. الأفضل في: مرجع مصقول بصفحة واحدة من أمر واحد، مع سمة افتراضية نظيفة وعدم الحاجة لإدارة قصة الاستضافة. القيود الصادقة: المخرجات هي ملف HTML واحد، لذا فهي صفحة مرجعية بدلاً من بوابة وثائق متعددة الصفحات، وتتواجد السمات والمعاينات الأكثر ثراءً في المستويات المدفوعة من Redocly. إذا كنت تقارنها بمقدمات مشابهة، فإن مقارنات بدائل Redocly و بدائل Scalar توضح المفاضلات.

Slate

Slate هو الخيار المختلف هنا: إنه ليس محولًا من المواصفات إلى الوثائق، بل هو مولد مواقع ثابتة لوثائق API المكتوبة يدويًا. تكتب Markdown، ويقوم Slate ببناء تخطيط الوثائق الكلاسيكي المكون من ثلاثة أعمدة (التنقل، المحتوى، وعينات الكود جنبًا إلى جنب) في موقع ثابت مستقل بذاته. إنه مدعوم بـ Middleman، لذا فهو يحتاج إلى Ruby.

# بعد استنساخ مستودع slate وتثبيت التبعيات
bundle exec middleman build

يؤدي ذلك إلى كتابة موقع ثابت كامل إلى مجلد build/ يمكنك استضافته في أي مكان. هنا يأتي دور Widdershins: قم بإنشاء Markdown من مواصفاتك، ثم اترك Slate يقوم بالعرض، وستحصل على محتوى يعتمد على المواصفات في تخطيط Slate.

الأفضل في: وثائق API المنسقة يدويًا، حيث تريد التحكم التحريري في البنية والنص. القيود الصادقة: إنه الخيار الأثقل في هذه القائمة لأنه يحتاج إلى سلسلة أدوات Ruby، ولا يقرأ OpenAPI بمفرده؛ أنت تغذيه بـ Markdown. إذا كانت وثائقك يتم إنشاؤها مباشرة من المواصفات ونادرًا ما يتم تحريرها يدويًا، فإن المحول وحده أخف وزنًا.

Apidog CLI (تصدير + توثيق)

تغطي الأدوات المفتوحة أعلاه كل شريحة على حدة: تحويل، عرض، أو استضافة. إذا كان واجهة برمجة التطبيقات الخاصة بك موجودة بالفعل في مشروع بدلاً من ملف YAML واحد، فإن ربطها ببعضها البعض هو الاحتكاك. وهنا يأتي دور ثنائي apidog-cli. إنه الرفيق الذي يعمل على سطر الأوامر لـ Apidog، ويحول تصدير واحد المشروع إلى Markdown أو HTML بدون خط بناء.

قم بتثبيته من npm والمصادقة باستخدام رمز مميز:

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

ثم قم بتصدير وثائق المشروع إلى Markdown أو HTML في أمر واحد:

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

يدير CLI أيضًا موارد الوثائق مباشرةً. يتعامل apidog doc مع مستندات Markdown الخاصة بالمشروع، ويدير apidog docs-site مواقع الوثائق المنشورة، حتى تتمكن من سرد وإنشاء وتحديث الوثائق من نص برمجي أو مهمة CI:

apidog doc list --project <projectId>
apidog docs-site list --project <projectId>

المخرجات هي JSON منظم، مما يسهل تمريره إلى خطوات أخرى أو تسليمه إلى وكيل. للحصول على نظرة شاملة للأوامر، يوضح الدليل الكامل لـ Apidog CLI عملية المصادقة والمشاريع وكل مجموعة أوامر.

هذا هو الإطار الصادق. Apidog ليس مفتوح المصدر، وليس ثنائيًا أحادي الغرض؛ إنه منصة مجانية (freemium)، ويتحدث CLI إلى مشروع مستضاف. كما أنه لا يقوم بفحص OpenAPI الخاص بك أو فرض دليل أسلوب؛ Redocly و Spectral يفعلان ذلك. ما يوفره CLI هو مسار متكامل واحد من مشروع API يتم صيانته إلى Markdown أو HTML قابل للمشاركة، بدلاً من ربط محول وعارض ومضيف يدويًا. إذا كنت تريد مسار تصدير Markdown على وجه التحديد، فإن مقالة مولد وثائق API مع تصدير Markdown تتناول سير العمل هذا بشكل أعمق.

كيف تختار

اختر الأداة التي تتناسب مع شكل مدخلاتك والمخرجات التي تحتاجها.

النسخة المختصرة: إذا كان لديك مواصفات أساسية وتريد Markdown لتقوم بالتثبيت، استخدم Widdershins. إذا كنت تريد صفحة HTML واحدة قابلة للمشاركة، فإن redocly build-docs هو الأسرع. إذا كنت تكتب الوثائق يدويًا وتريد تصميمًا مناسبًا، فاستخدم Slate. وإذا كانت واجهة برمجة التطبيقات (API) الخاصة بك موجودة بالفعل في مشروع وتريد التصدير بالإضافة إلى إدارة الوثائق في CLI واحد، فاستخدم Apidog. للحصول على نظرة عامة مجانية شاملة، فإن ملخص أدوات توثيق API المجانية يجمع كل ذلك.

الخلاصة

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

إذا كانت هذه الحالة الأخيرة تنطبق عليك، قم بتنزيل Apidog وجرب apidog export على مشروع؛ سيتم إدراجه بسلاسة في مهمة CI بحيث تتم إعادة بناء وثائقك في كل مرة تتغير فيها واجهة برمجة التطبيقات.