تصبح مستندات واجهة برمجة التطبيقات قديمة بمجرد قيام شخص ما بتعديل المواصفات ونسيان إعادة إنشاء المرجع. الحل هو التوقف عن التعامل مع التوثيق كخطوة يدوية. إذا كان بإمكانك إنتاج المستندات بأمر واحد، فيمكنك ربط هذا الأمر بخطوات التكامل المستمر (CI) والسماح بتشغيله عند كل دمج.
للقيام بذلك من الطرفية (terminal) مزايا أخرى. الأوامر قابلة للبرمجة، وتترك فرقًا يمكنك مراجعته، ويمكن لوكيل الذكاء الاصطناعي أو مشغل التكامل المستمر (CI runner) تشغيلها دون الحاجة إلى فتح أي متصفح. لا نقر على واجهة رسومية، ولا "هل تذكرت النقر على تصدير؟".
يوضح هذا الدليل المسار المفتوح العام أولاً: تحويل ملف OpenAPI إلى مرجع HTML مستقل أو ملف Markdown بأمر واحد. ثم يتعمق في مسار Apidog CLI، والذي يسحب مستنداتك مباشرة من مشروع حي بحيث يبقى مصدر الحقيقة والإخراج متزامنين. إذا كنت تريد المزيد من المعلومات حول هذا المجال، فراجع قائمتنا لأفضل 10 أدوات لتوثيق REST API وأدوات توثيق API المجانية التي تستحق المعرفة.
تحتاج إلى شيء واحد للمتابعة: ملف OpenAPI 3.x. تقبل معظم هذه الأوامر ملفي openapi.yaml أو openapi.json بالتبادل.
بناء مرجع HTML باستخدام Redocly CLI
Redocly CLI هي أسرع طريقة لتحويل وصف OpenAPI إلى صفحة HTML مصقولة ومكتفية ذاتيًا. يقوم هذا الأداة بعرض المواصفات الخاصة بك باستخدام Redoc ويكتب كل شيء (الأنماط، والسكربتات، والمحتوى) في ملف واحد يمكنك استضافته في أي مكان أو إرساله بالبريد الإلكتروني إلى زميل.
قم بتثبيته عالميًا، أو تخطى التثبيت وقم بتشغيله باستخدام npx:
npm install @redocly/cli -g
ثم وجهه إلى مواصفاتك:
redocly build-docs openapi.yaml
بشكل افتراضي، يكتب هذا الأمر ملف redoc-static.html في الدليل الحالي. افتح هذا الملف في متصفح وسيكون لديك مرجع API كامل بثلاث لوحات. للتحكم في اسم الملف أو المسار، استخدم --output:
redocly build-docs openapi.yaml --output docs/index.html
هذا هو سير العمل بالكامل. ملف إدخال واحد، أمر واحد، ناتج HTML واحد. يعمل مع أوصاف Swagger 2.0 وOpenAPI 3.0/3.1، لذا فإن معظم المواصفات الحالية تُعرض دون تغييرات. المفاضلة هي النطاق: يمنحك build-docs صفحة مرجعية ولا شيء آخر. أما الأدلة الطويلة، والبرامج التعليمية، وصفحات البدء السريع فتقع خارج هذا النطاق.
إنشاء Markdown باستخدام Widdershins
أحيانًا لا ترغب في HTML. بل تريد Markdown يمكنك إضافته إلى موقع توثيق، أو مولد مواقع ثابتة، أو مجلد docs/ لمستودع. يقوم Widdershins بتحويل تعريف OpenAPI أو Swagger أو AsyncAPI إلى Markdown متوافق مع Slate.
قم بتثبيته من npm:
npm install -g widdershins
ثم قم بتحويل مواصفاتك، وإرسال المخرج إلى ملف باستخدام -o:
widdershins openapi.yaml -o api.md
احذف -o وسيقوم Widdershins بالطباعة إلى stdout، وهو مفيد إذا كنت ترغب في توجيه الإخراج إلى مكان آخر. يمكنك أيضًا تبديل علامات تبويب اللغة لعينات التعليمات البرمجية:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins مناسب تمامًا عندما تكون عملية توثيقك تعتمد على Markdown أولاً. إذا كنت تقوم ببناء تدفق تصدير Markdown أوسع، فإن دليلنا حول استخدام مولد مستندات API مع تصدير Markdown يغطي الأدوات المحيطة. العيب في كل من Redocly وWiddershins هو نفسه: إنهما يقرآن ملفًا ثابتًا. إذا كان تعريف واجهة برمجة التطبيقات الخاصة بك يعيش في أداة تصميم وينحرف عن الملف الموجود على القرص، فأنت تقوم بتوثيق مواصفات الأمس.
التوثيق من مشروع حي باستخدام Apidog CLI
هنا يبرز المسار المتكامل. Apidog ليس مفتوح المصدر، ولكن طبقته المجانية بالإضافة إلى apidog-cli يوفران لك بديلاً لربط أدوات منفصلة معًا: نقاط النهاية والمخططات والمستندات المكتوبة كلها تعيش في مشروع واحد، وتقوم واجهة سطر الأوامر بالتصدير من هذا المشروع عند الطلب. لا يحدث أي انحراف، لأن التصدير يقرأ نفس المصدر الذي يقوم فريقك بتحريره.
قم بتثبيت واجهة سطر الأوامر (CLI) من npm:
npm install -g apidog-cli
إذا كنت تقوم بالإعداد للمرة الأولى، فإن دليل تثبيت Apidog CLI يغطي إصدارات Node وإعداد PATH. ثم قم بالمصادقة مرة واحدة باستخدام رمز وصول شخصي:
apidog login --with-token <TOKEN>
يتم تخزين الرمز، لذا لا تحتاج إلى تمريره في كل استدعاء. من هنا، يتم تشغيل كل شيء مقابل معرّف مشروع. أضف --help إلى أي أمر لرؤية علاماته الدقيقة قبل تشغيله.
استيراد مواصفات إلى المشروع
إذا كانت واجهة برمجة التطبيقات الخاصة بك موجودة بالفعل في ملف OpenAPI، فقم بإحضارها إلى مشروع ليكون لدى CLI ما يمكن تصديره:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
يقبل apidog import تنسيقات OpenAPI 3.x وSwagger 2.0 وPostman وApidog، بحيث يمكنك سحب مجموعة Postman أو تصدير Apidog موجود بنفس الطريقة. بمجرد استيراد المواصفات، يصبح المصدر الحي الذي تقرأ منه كل الأشياء الأخرى.
تصدير مستندات قابلة للقراءة البشرية
هذا هو الأمر الأساسي. يقوم apidog export بكتابة OpenAPI، HTML، Markdown، أو Postman، لذا قم بتشغيل --help أولاً لرؤية التنسيق الدقيق وعلامات الإخراج التي يدعمها إصدارك، ثم قم بتصدير توثيق المشروع إلى Markdown:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
افتح api-docs.md وسيكون لديك مرجع كامل تم إنشاؤه من الحالة الحالية للمشروع. هل تريد HTML بدلاً من ذلك؟ غيّر علامة واحدة فقط:
apidog export --project <projectId> --format html --output ./api-docs.html
يمكنك أيضًا التصدير مرة أخرى إلى OpenAPI عندما تريد مواصفات محمولة لتمريرها إلى الأطراف النهائية:
apidog export --project <projectId> --format openapi --output ./openapi.json
إذا كان مشروعك يحتوي على عدة خدمات وترغب في توثيق جزء منه فقط، فإن التصدير يدعم تضييق النطاق. تحقق من apidog export --help لمعرفة علامات النطاق والمعرّف في إصدارك، حيث يمكن لمشروع واحد أن يصدر ملف توثيق واحد لكل خدمة بهذه الطريقة.
إدارة الأدلة المكتوبة، وليس المرجع فقط
المرجع الذي تم إنشاؤه من مخططك ليس سوى نصف القصة. النصف الآخر هو الشرح النصي: أدلة البدء، إرشادات المصادقة، ملاحظات الترحيل. في Apidog، تعيش هذه المستندات في شجرة مستندات المشروع كوثائق Markdown، وتديرها واجهة سطر الأوامر (CLI) باستخدام مجموعة أوامر doc.
ابدأ بقراءة تعليمات المجموعة لتضمن أنك تعمل بالعلامات الدقيقة التي يوفرها إصدارك:
apidog doc --help
apidog doc list --project <projectId>
من هناك، يتبع سير العمل نفس شكل كل شيء آخر في واجهة سطر الأوامر: قم بتشغيل الأمر مقابل مشروعك، واقرأ نتيجة JSON، واتبع agentHints.nextSteps التي يعيدها. عندما يطلب أمر حمولة JSON، يمكن لـ CLI طباعة المخطط الذي يتوقعه والتحقق من صحة ملفك مقابله قبل إرسال أي شيء، بحيث تكتشف الحقل المفقود على جهازك بدلاً من أن يحدث ذلك في استدعاء فاشل. تحقق من apidog cli-schema --help للحصول على الأمر الفرعي للتحقق الدقيق.
نشر موقع توثيق
عندما يصبح المرجع والأدلة جاهزة، يمكنك إدارة التوثيق المنشور من الطرفية أيضًا. يغطي ذلك أمران، وقراءة تعليماتهما أولاً يوفر عليك تخمين علامة:
apidog docs-site --help
apidog shared-doc --help
ملاحظة تسمية تسبب بعض الالتباس: doc هو مستند Markdown داخل شجرة API للمشروع، وdocs-site يدير موقع التوثيق العام المستضاف، وshared-doc يدير روابط التوثيق القابلة للمشاركة. استخدم docs-site عندما تريد موقعًا عامًا يتم تعريفه من الطرفية بدلاً من النقر عليه في واجهة المستخدم، وshared-doc عندما تريد مجرد رابط لتقديمه لشريك. الفائدة هي أن النشر يصبح خطوة مبرمجة: عندما تتغير مواصفاتك، تقوم بإعادة استيراد أو تعديل المشروع، ثم تقوم بتشغيل أمر النشر مرة أخرى، وتعكس المستندات المستضافة التحديث.
ربطها بخطوات التكامل المستمر (CI)
السبب في تشغيل أي من هذا من واجهة سطر الأوامر (CLI) هو التكرارية. بمجرد أن تعمل الأوامر محليًا، فإنها تعمل في مسار عمل. تبدو خطوة GitHub Actions بسيطة تعيد إنشاء وتلتزم بمرجع Markdown الخاص بك عند كل دفعة كالتالي:
- 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
استبدل بـ redocly build-docs أو widdershins وسيكون الشكل متطابقًا. تتوقف المستندات عن كونها مهمة يتذكر شخص ما القيام بها وتصبح ناتج بناء يعيد إنشاء نفسه. للحصول على مرجع الأوامر الكامل، راجع الدليل الكامل لـ Apidog CLI.
عقبات شائعة
معرف المشروع خاطئ أو مفقود. كل استدعاءات Apidog export وdoc وdocs-site تحتاج إلى --project <projectId>. المعرّف موجود في إعدادات المشروع، وليس اسم المشروع المقروء بشريًا. إذا أخطأ أمر ما يشتكي من المشروع، فهذا هو السبب في معظم الحالات.
الرمز غير معين في CI. يقوم apidog login بتخزين الرمز على الجهاز الذي يشغله. في مشغل CI جديد، لا يوجد رمز مخزن، لذلك يجب عليك تشغيل login --with-token في نفس المهمة قبل أي تصدير. قم بتخزين الرمز كسر، وليس أبدًا في ملف سير العمل.
تصديرات الملفات القديمة. يقرأ Redocly وWiddershins أي ملف تعطيهما إياه. إذا كان ملف openapi.yaml الخاص بك قديمًا، فإن مستنداتك ستكون قديمة أيضًا. هذا هو بالضبط الانحراف الذي يتجنبه مسار Apidog عن طريق التصدير من المشروع الحي بدلاً من ملف على القرص.
التخمين في العلامات بدلاً من قراءة --help. يمكن أن تختلف العلامات الدقيقة للأوامر export، وdoc، وdocs-site، وshared-doc باختلاف إصدار CLI. قم بتشغيل apidog <command> --help واعمل بناءً على ما يطبعه بدلاً من علامة تتذكرها جزئيًا. يستغرق الأمر ثانيتين ويوفر عليك فشل البناء.
الخلاصة
توثيق واجهة برمجة تطبيقات من الطرفية يعتمد على اختيار الإخراج الصحيح. استخدم Redocly CLI عندما تريد مرجع HTML مستقل، وWiddershins عندما تريد Markdown لموقع توثيق، وApidog CLI عندما تريد مرجعًا بالإضافة إلى أدلة مكتوبة بالإضافة إلى موقع منشور، كلها مصدّرة من مصدر حي واحد. الخيار الأخير هو الذي يحافظ على مصداقية مستنداتك، لأن التصدير والشيء الذي يقوم فريقك بتحريره هما نفس المشروع.
كل أمر هنا قابل للبرمجة النصية، مما يعني أن كل واحد منها ينتمي إلى التكامل المستمر (CI). قم بإعداده مرة واحدة وسيعاد إنشاء توثيقك تلقائيًا عند كل تغيير. قم بتنزيل Apidog للحصول على واجهة سطر الأوامر وتجربة سير عمل التصدير مقابل مشروعك الخاص، أو اقرأ المزيد حول كيفية تناسب Apidog مع سير عمل يعتمد على API أولاً.