كيفية الانتقال من Redocly إلى Apidog دون فقدان سير عمل التوثيق ككود

إذا كنت تشغّل بوابة المطورين الخاصة بك على Redocly، فأنت تعمل بالفعل بالطريقة التي تريدها معظم فرق API: يبقى openapi.yaml في Git، والأدلة بصيغة Markdown، ودفعة واحدة تحدّث الوثائق. الخوف عند تغيير الأدوات هو فقدان هذه الحلقة وانتهاء الأمر بتحرير الوثائق يدويًا في واجهة ويب.

لست مضطرًا لذلك. يحافظ وضع Spec-first Mode من Apidog على مواصفتك وملفات Markdown الخاصة بك في المستودع نفسه، ويزامن عند كل دفعة عبر webhook، وينشر بوابة تضم الأدلة ومرجع API في شريط جانبي واحد. يشرح هذا الدليل الترحيل خطوة بخطوة، بما في ذلك الجزء الوحيد الذي لا ينتقل تلقائيًا: المحتوى الطويل الذي يحتفظ به كثير من مستخدمي Redocly داخل info.description وtags[].description.

إذا كنت لا تزال تقارن الأدوات، فابدأ بـ Apidog مقابل Redocly أو القائمة الأوسع من بدائل Redocly. تفترض هذه المقالة أنك اخترت Apidog وتريد الانتقال دون كسر سير عملك.

ما الذي ينتقل وما الذي لا ينتقل

اختبرنا هذا الترحيل باستخدام مواصفة إنتاجية حقيقية: OpenAPI 3.0.3، و62 عملية عبر 13 وسمًا، مع محتوى البدء والمصادقة والتكامل مكتوبًا في حقول الوصف الخاصة بالمواصفة. إليك ما حدث عند الاستيراد.

تنتقل مرجعية API دون أي تعديلات. الفجوة هي المحتوى السردي.

لماذا لا تُعرض حقول الوصف لديك بالطريقة نفسها

يعامل Redoc، العارض الذي يقف خلف وثائق مرجع Redocly، info.description كمستند مصغّر. يصبح كل عنوان Markdown بداخله مدخلًا في الشريط الجانبي، لذا غالبًا ما تكتب الفرق أدلة «البدء» و«المصادقة» بالكامل هناك. تُعرض أوصاف الوسوم كنص تمهيدي في أعلى كل مجموعة وسوم.

هذا تقليد خاص بـ Redoc، وليس جزءًا من مواصفة OpenAPI. لا تُعرّف المواصفة description إلا كسلسلة CommonMark. يحتفظ Apidog، مثل معظم البوابات، بالأدلة كمستندات Markdown مستقلة ويحتفظ بالمواصفة للمرجع. يُظهر النشر الافتراضي بعد الاستيراد مرجع API فقط، من دون الأدلة التي كتبتها في حقول الوصف.

الإصلاح هو نقل لمرة واحدة: أخرج هذا المحتوى من YAML إلى ملفات Markdown بجواره. بعد ذلك، يبقى كل شيء مدفوعًا بـ Git.

بنية المستودع الهدف

هذه هي البنية التي تحققنا منها:

your-repo/
├── openapi.yaml              # source of truth for the API reference
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

يقود openapi.yaml مرجع API. يصبح كل ملف في docs/ صفحة في الشريط الجانبي للبوابة. يمكن للصور التي تشير إليها ملفات Markdown تلك أن توجد في المستودع نفسه وتتزامن معها.

إذا كنت تستخدم sidebars.yaml من Redocly لترتيب التنقل لديك، فأبقِه كمرجع. ستضبط الترتيب نفسه مرة واحدة في إعدادات موقع الوثائق في Apidog.

الترحيل خطوة بخطوة

1. افحص ما يوجد داخل حقول الوصف

قبل نقل أي شيء، انظر كم من المحتوى يوجد في المواصفة. باستخدام yq:

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

قائمة العناوين هي قائمة ملفات docs/ المستقبلية لديك. في اختبارنا، انقسم info.description إلى ملفَي Markdown، وأصبحت أوصاف الوسوم صفحات مقدمة لكل مجلد بالإضافة إلى ملف Markdown إضافي واحد.

2. قسّم info.description إلى ملفات Markdown

انسخ كل قسم من المستوى الأعلى إلى ملفه الخاص ضمن docs/. أبقِ العناوين وعينات الشيفرة والروابط. ثم قلّص info.description في المواصفة إلى ملخص من فقرة واحدة، بحيث يوجد المحتوى في مكان واحد فقط.

احترس من ميزتين خاصتين بـ Redoc أثناء النسخ:

• <SecurityDefinitions /> والوسوم المشابهة في Redoc لا تُعرض خارج Redoc. استبدلها بقسم مكتوب قصير يرتبط بمخططات الأمان في المرجع.
• روابط مثل #tag/Payments تشير إلى مراسي Redoc. حدّثها إلى روابط وثائق Apidog أو المجلدات المطابقة بعد أول نشر.

3. اربط المستودع في وضع Spec-first Mode

أنشئ مشروعًا في Spec-first Mode، واربط مستودعك (GitHub أو GitLab أو Azure DevOps أو Bitbucket)، ووجّهه إلى openapi.yaml ومجلد docs/، وثبّت webhook. من ذلك الحين فصاعدًا، تؤدي دفعة إلى الفرع المتتبَّع إلى تحديث المشروع.

بعد أول مزامنة، تعرض مساحة عمل Specs مواصفتك وبقية المستودع. تسرد علامة تبويب APIs العمليات المحللة من openapi.yaml، وتحتوي Docs على صفحات Markdown الخاصة بك، وتعكس All files المستودع.

webhook هو ما يحافظ على هذا كسير عمل الوثائق كشيفرة. من دونه، سيتعين عليك تشغيل المزامنات يدويًا. لمراجعة سبب أهمية ذلك، راجع دليلنا حول الوثائق كشيفرة.

4. انشر موقع الوثائق واضبط التنقل

انشر موقع وثائق من المشروع ورتّب الشريط الجانبي. الترتيب الذي يريده معظم مستخدمي Redocly، والذي أعدنا إنتاجه، هو:

1. البدء
2. المصادقة
3. أدلة التكامل
4. مرجع API (مجلدات نقاط النهاية من الوسوم)

تختلط صفحات Markdown ومجلدات API بحرية في شجرة واحدة، لذا يمكنك مطابقة شريطك الجانبي الحالي في Redocly عن قرب.

5. أضف نطاقك المخصص

وجّه CNAME مثل developers.example.com إلى موقع الوثائق. النطاقات المخصصة متاحة في الخطة المجانية.

دع وكيل البرمجة لديك يهاجر أوصاف الوسوم باستخدام Apidog CLI

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

يمنح Apidog CLI كلاً من Claude Code وCodex وCursor أو أي وكيل طرفية وصولًا منظمًا بصيغة JSON إلى مشروعك، بما في ذلك مجلدات نقاط النهاية. أعدّه مرة واحدة:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

يثبّت السطر الأخير مهارة Apidog حتى يعرف وكيلك الأوامر دون تخمين. يغطي دليل التثبيت الرموز والنشر الخاص.

ثم أعطِ وكيلك مطالبة واحدة:

اقرأ openapi.yaml. لكل وسم له وصف، اعثر على مجلد نقاط النهاية المطابق في مشروع Apidog <PROJECT_ID> واضبط وصف ذلك المجلد على وصف الوسم. تحقق من كل حمولة باستخدام apidog cli-schema validate folder-update قبل الكتابة. اعرض لي قائمة المجلدات التي غيّرتها.

إليك ما يشغّله الوكيل:

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

يقبل مخطط folder-update كلاً من name وparentId وdescription، وdescription مدعوم في مجلدات نقاط النهاية ومجلدات سيناريوهات الاختبار. بالنسبة إلى الأدلة التي لا تنتمي إلى وسم واحد، يمكن للوكيل استخدام apidog doc list وapidog doc create بالطريقة نفسها، بعد قراءة apidog cli-schema get doc-create.

لعرض مقدمة المجلد على الموقع المنشور، اضبط Folder Contents Displaying Setting في إعدادات المجلد ضمن Documentation Settings after Publication.

تحذير صريح واحد: إظهار أوصاف الوسوم كصفحات مقدمة لكل فئة ينجح، لكنه يعتمد على مسار أقل توثيقًا. اختبره على مجلدين أو ثلاثة في مساحة عملك قبل أن تعتمد عليه لكلها. لمزيد من العمل على المواصفات بقيادة الوكيل، راجع استخدام Apidog CLI في Claude Code والسماح لوكيل بتحديث مواصفة API لديك.

ما الذي يبقى خارج Git

يحتفظ مشروع Spec-first بواجهة API وملفات Markdown الخاصة بك في Git. تعيش بعض إعدادات البوابة في واجهة Apidog ولا تخضع للتحكم بالإصدارات:

هذه عناصر تُضبط مرة واحدة. تلمسها عند إضافة قسم جديد من المستوى الأعلى، وليس عند كل تغيير في المحتوى. يحتفظ Redocly بالمزيد من ذلك في redocly.yaml وsidebars.yaml، لذا إذا كنت تراجع تغييرات التنقل في طلبات السحب اليوم، فخطط لانتقال ذلك إلى الواجهة.

الخطة والتسعير

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

Redocly مقابل Apidog بعد الترحيل

المقايضة بسيطة. تخسر التنقل المعرّف في YAML. وتكسب الاختبار والمحاكاة وCLI مناسبًا للوكلاء على المواصفة نفسها التي تأتي منها وثائقك. للحصول على تفصيل CLI مقابل CLI، اقرأ Apidog CLI مقابل Redocly CLI.

الأسئلة الشائعة

هل ستبقى روابطي المستضافة على Redocly تعمل؟ ليس تلقائيًا. تتغير مسارات الصفحات. إذا كانت بوابتك القديمة تحتوي على روابط أدلة عالية الزيارات، فأضف عمليات إعادة توجيه على طبقة DNS أو proxy للصفحات الرئيسية بعد تبديل النطاق.

هل يجب أن أعيد كتابة مواصفة OpenAPI؟ لا. تُستورد المواصفة كما هي. أنت فقط تنقل المحتوى السردي خارج info.description وtags[].description إلى ملفات Markdown.

هل يمكنني الاحتفاظ بـ x-tagGroups؟ استخدم المجلدات للتجميع بدلاً من ذلك. يصبح كل وسم مجلدًا، ويمكنك تداخل المجلدات لإعادة إنتاج مجموعات الوسوم لديك.

كيف يقارن هذا بالترحيل من Stoplight؟ الشكل مشابه: المواصفة في Git، وMarkdown بجوارها، ومزامنة عبر webhook. راجع كيفية الترحيل من Stoplight إلى Apidog إذا كنت تشغّل الأداتين معًا.

ماذا لو تصرفت خطوة بشكل مختلف في مساحة عملي؟ جاءت نتائجنا من بيئة اختبار. أعد تشغيل الاستيراد على فرع أولاً وقارن البوابة المنشورة ببوابتك الحالية قبل تبديل DNS.

أنجز الانتقال في فترة بعد الظهر

الترحيل من Redocly إلى Apidog هو في الغالب نقل محتوى. تُستورد مواصفتك كما هي. تنتقل أدلتك خارج حقول الوصف إلى مجلد docs/ مرة واحدة. ويُبقي webhook كل شيء متزامنًا بعد ذلك. دع وكيلك يتعامل مع عمل أوصاف الوسوم المتكرر باستخدام Apidog CLI، واقضِ وقتك في فحص البوابة المنشورة صفحة بصفحة.

نزّل Apidog واربط مستودعك بوضع Spec-first Mode لبدء الترحيل.