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

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

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

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

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

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

البرمجيات مفتوحة المصدر ليست مجرد "مجانية للتنزيل". بالنسبة لأدوات التوثيق التي ستدمجها في عملية بناء، هناك ثلاثة أمور تحدد ما إذا كانت الأداة ملكًا لك حقًا.

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

مخرجات قابلة للاستضافة الذاتية. الهدف من الوثائق المفتوحة هو ألا يعتمد أي شيء على خوادم البائع. تقوم هذه الأدوات بكتابة ملفات ثابتة: Markdown يمكنك تثبيتها، أو صفحة HTML واحدة، أو مجلد من HTML/CSS/JS. يمكنك استضافتها على GitHub Pages أو S3 أو خادم Nginx عادي، وستظل تعمل بغض النظر عما إذا كان المشروع الذي يدعم الأداة لا يزال نشطًا.

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

بالنسبة لجانب "التكلفة الصفرية" عبر كل من الخيارات المفتوحة و"فريميوم"، فإن قائمة أدوات توثيق واجهة برمجة التطبيقات المجانية هي القطعة المكملة. الآن ننتقل إلى الأدوات.

Redocly CLI

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

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

هذا ينشئ ملف HTML واحد مبني على Redoc. افتحه محليًا، أو ضعه على أي مضيف ثابت، أو أرفقه بإصدار. لا شيء يتصل بالإنترنت، ويمكنك تشغيله دون اتصال بالشبكة بمجرد تخزين الحزمة مؤقتًا.

الأفضل في: مرجع واجهة برمجة تطبيقات نظيف من صفحة واحدة من أمر واحد، مرخص بـ MIT وقابل للاستضافة الذاتية. حدود صريحة: المخرجات عبارة عن صفحة واحدة، لذا فهي مرجع وليست بوابة متعددة الصفحات، والتصميم الغني يقع ضمن الفئة المدفوعة. إذا كنت تقارن محركات العرض ببعضها البعض، فإن مقارنة بدائل Redocly توضح أين يقع الخط الفاصل للميزات المفتوحة.

Widdershins

Widdershins هو محول بحت بموجب ترخيص MIT. يقرأ OpenAPI 3 أو Swagger 2 أو AsyncAPI ويصدر Markdown؛ هذا هو عمله بالكامل. نظرًا لأن المخرجات هي Markdown عادي، فأنت تملكها بالكامل: يمكنك تثبيتها (commit)، أو مقارنتها في طلب سحب، أو إدخالها في أي موقع ثابت تقوم بتشغيله بالفعل.

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

الـ Markdown الذي يكتبه متوافق مع Slate، مما يجعله يتوافق بسلاسة مع مولدات المواقع لاحقًا في هذه القائمة. أعلام مفيدة: `--omitHeader` يحذف المعلومات الأولية، و`--language_tabs` يختار لغات أمثلة الكود.

الأفضل في: الحصول على محتوى المواصفات بصيغة Markdown قابلة للتحكم في الإصدارات مع عدم وجود قيود. حدود صريحة: Markdown هو كل ما تحصل عليه. لا يوجد تنسيق ولا موقع مُقدم (rendered)، لذا فإن Widdershins هو نصف خط أنابيب؛ شيء آخر يحول Markdown إلى صفحات.

OpenAPI Generator

OpenAPI Generator مرخص بترخيص Apache 2.0 ويديره المجتمع، وقد تفرع من Swagger Codegen في عام 2018. وهو معروف بشكل خاص بمجموعات تطوير البرمجيات (SDKs) للعملاء، ولكنه يأتي أيضًا بمولدات للتوثيق: يقوم المولد markdown بكتابة مجلد من ملفات Markdown، ويقوم html2 بكتابة صفحة HTML واحدة مكتفية ذاتيًا.

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/

يجعل ترخيص Apache 2.0 ومنح براءات الاختراع الخاص به أمر الموافقة سهلاً للفرق القانونية الحذرة، ويعتبر المشروع واحدًا من أكثر المشاريع التي يتم صيانتها بنشاط في هذا المجال.

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

Swagger Codegen

Swagger Codegen هو المولد الأصلي القائم على القوالب من فريق Swagger، ومرخص بترخيص Apache 2.0. وهو يسبق تفرع OpenAPI Generator ولا يزال يتم صيانته بواسطة SmartBear. لإنشاء الوثائق، يوفر مسارين: html لمرجع ثابت من صفحة واحدة، وdynamic-html لموقع تفاعلي صغير.

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

يتشارك المشروعان في الحمض النووي (DNA) والعديد من الخيارات، لذلك إذا كان فريقك قد اعتمد بالفعل سلسلة أدوات Swagger، فهذا يبقيك ضمنها.

الأفضل في: الفرق التي استثمرت بالفعل في نظام Swagger البيئي والتي ترغب في الحصول على وثائق من نفس أداة Apache 2.0 التي تولد مكوناتها (stubs). حدود صريحة: تعتمد على Java مثل OpenAPI Generator، ويتطور ببطء أكثر من التفرع المجتمعي. بالنسبة لمعظم الإعدادات الجديدة، يُعد OpenAPI Generator الخيار الأكثر نشاطًا؛ بينما يتفوق Swagger Codegen في الاستمرارية.

Docusaurus مع إضافة OpenAPI

إذا لم تكن صفحة HTML واحدة كافية وتريد موقع وثائق حقيقي ومُوَفَّر بنسخ، فإن Docusaurus هو الركيزة مفتوحة المصدر. إنه مرخص بترخيص MIT، وقد بنته Meta، وهو أحد أكثر مولدات المواقع الثابتة استخدامًا على الويب. بحد ذاته، يقوم بعرض Markdown و MDX؛ وتضيف إضافة docusaurus-openapi-docs، وهي أيضًا مرخصة بـ MIT ويتم صيانتها بواسطة Palo Alto Networks، توليد المواصفات إلى وثائق.

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

بعد تهيئة الإضافة بمسار مواصفاتك، يقوم gen-api-docs بتحويل ملف OpenAPI إلى صفحات MDX يتم عرضها داخل موقع Docusaurus، مع لوحة "جرّبها" وتصفح جانبي.

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

Slate

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

# after cloning your Slate fork and running bundle install
bundle exec middleman build

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

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

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

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

هذه هي الفجوة التي يسدها الملف الثنائي 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

عملية تصدير واحدة تحول المشروع إلى Markdown أو HTML دون الحاجة إلى خط أنابيب بناء، ويقوم apidog doc وapidog docs-site بإدارة موارد الوثائق من خلال سكريبت. المخرجات هي JSON منظم، لذا يمكن توجيهها بسلاسة إلى CI أو وكيل. يشرح الدليل الكامل لـ Apidog CLI عملية المصادقة وكل مجموعة أوامر. إذا كان سير عمل تصدير Markdown هو ما تبحث عنه، فإن مقالة مولد وثائق API مع تصدير Markdown تتعمق أكثر.

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

كيف تختار

طابق الترخيص والمخرجات مع ما يحتاج فريقك لامتلاكه.

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

خلاصة

يعتمد اختيار أداة توثيق سطر الأوامر (CLI) مفتوحة المصدر على الترخيص، المخرجات، ومكان تواجد وثائقك. يتيح لك ترخيصا MIT و Apache 2.0 استخدام وتعديل واستضافة الأدوات بنفسك دون تكلفة مقعد، لذا اختر أصغر أداة تنتج المخرجات التي تحتاجها: Redocly CLI لصفحة، Widdershins لـ Markdown، OpenAPI Generator أو Swagger Codegen للوثائق بجانب SDKs الخاصة بك، Docusaurus لبوابة، Slate للصفحات المنتقاة يدويًا.

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