تشغيل Try it في OpenAPI بأمان: الاعتمادات وCORS والإصدارات والمراجع الخارجية
انشر وحدة Try it بمفاتيح اختبار فقط وسلوك صحيح للمتصفح وCORS وتوافق للإصدارات والخوادم ومراجع خارجية آمنة واختبارات RTL.
· 13 دقائق قراءة · بقلم فريق Nibleaf
تحوّل وحدة تجربة API التوثيق إلى عميل نشط. لا تكون هذه الميزة مفيدة إلا عندما يتطابق طلب المتصفح ونموذج الاعتماد والخادم المختار وإصدار المخطط والرد المعروض مع الوعد المحيط بزر «جرّب».
نجاح أمر curl لا يثبت نجاح الوحدة؛ فالمتصفحات تفرض سياسات الأصل وملفات الارتباط التي لا يفرضها عميل سطر الأوامر. كما قد ينجح طلب المتصفح مع بقائه خطرًا إذا أرسل اعتماد إنتاج أو تبع مرجعًا خارجيًا غير مراجع.
افصل دليل المتصفح عن دليل curl
احتفظ بالاختبارين. يتحقق curl من DNS وTLS والتوجيه وتوثيق الخادم وعقد API من دون سياسة المتصفح. ويتحقق متصفح حقيقي من أصل صفحة التوثيق والطلب التمهيدي والطرق والترويسات المسموحة ووضع الاعتماد وخصائص ملفات الارتباط والتحويلات وإتاحة قراءة الرد.
سجّل رابط التوثيق ورابط خادم API والعملية وترويسات الطلب بعد حذف الأسرار والحالة وترويسات CORS ذات الصلة وشكل الرد. وسم الدليل بوضوح: متصفح أو سطر أوامر. لا تجعل أحدهما بديلًا للآخر.
استخدم اعتمادًا وبيانات للاختبار فقط
وجّه الوحدة إلى بيئة اختبار أو مؤسسة تجريبية معزولة بإحكام. أصدر اعتمادًا قصير العمر محدودًا بعمليات الاختبار الموثقة وبيانات اصطناعية. لا تضمّن مفتاح إنتاج في HTML أو JavaScript أو أمثلة OpenAPI أو الصور أو السجلات أو تخزين المتصفح المشترك.
للعمليات ذات الأثر، قدم عينة قابلة للحذف وتحذيرًا ظاهرًا. استخدم مفاتيح عدم التكرار وحصصًا محدودة. عطّل عمليات الإنتاج الخطرة في الوحدة العامة حتى لو وصفها المخطط الأساسي.
مثّل كل طريقة توثيق بصدق
لمفتاح API، وضّح موضع الترويسة أو الاستعلام واستخدم مفتاح اختبار قابلًا للإبطال. تجنب الاعتماد في الاستعلام لأن الروابط تتسرب إلى التاريخ والسجلات. مع OAuth استخدم مسار authorization code مع PKCE حيث يلائم، وروابط عودة دقيقة، ونطاقات ضيقة، ومسار خروج وإبطال موثقًا.
تحتاج واجهات ملفات الارتباط إلى وضع اعتماد مقصود وخصائص SameSite وSecure متوافقة وحماية CSRF لتغيير الحالة وسياسة أصل لا تجمع النجمة مع الاعتمادات. لا تعرض الوحدة كأنها مسجلة الخروج بينما يفوض ملف ارتباط قديم الطلب بصمت.
تحقق من الطلب التمهيدي وCORS
قد يرسل المتصفح طلب OPTIONS قبل الطلب الموثق. اختبره من أصل التوثيق الحقيقي لكل طريقة وترويسة غير بسيطة تستخدمها الوحدة. ينبغي للخادم السماح بالأصل والطرق والترويسات المطلوبة تحديدًا، وتنويع الذاكرة المؤقتة وفق Origin عندما تختلف الردود، وكشف ترويسات الرد التي تقرؤها الواجهة فقط.
اتبع التحويلات أثناء الاختبار. يحتاج التحويل إلى مضيف آخر سلوك CORS خاصًا به، ويجب ألا تتسرب ترويسة التفويض إلى أصل غير مقصود. اختبر الأخطاء أيضًا؛ رد 401 أو 422 لا يستطيع المتصفح قراءته ينتج واجهة مضللة.
اربط الوحدة بإصدار وخادم
ينبغي لكل إصدار توثيق تحميل لقطة OpenAPI المطابقة. اعرض إصدار API والخادم المختار قرب زر التجربة، وأدرجهما في الأمثلة المنسوخة. يجب أن تتفق تسميات latest وstable وbeta ونهاية الدعم مع سياسة إصدار التوثيق وسجل التغييرات.
لا تجعل صفحة توثيق قديمة تنفذ بصمت على أحدث خادم إنتاج. إذا تقاعد إصدار API، فعطّل التنفيذ أو وجّهه إلى بيئة توافق آمنة واشرح القيد. اختبر الروابط العميقة والصفحات المخزنة بعد تغيير الخادم الافتراضي.
حافظ على توافق المخطط والخادم وسجل التغييرات
اجعل النشر مشروطًا بثلاث مقارنات: العمليات والمخططات المعروضة مقابل ملف OpenAPI المثبت؛ والخوادم المعدة مقابل جرد النشر؛ والتغييرات الكاسرة مقابل سجل التغيير ودليل الترحيل.
سجّل بصمة الملف ومعرف الإصدار أو النشر. قد يجعل رابط مخطط قابلًا للتغيير توثيق الأمس يعرض مخطط الغد من دون مراجعة للمحتوى.
عامل $ref الخارجي كحد جلب
يمكن أن يطلق المرجع الخارجي وصولًا شبكيًا على الخادم أو أثناء البناء. اسمح فقط بالمخططات والأصول المراجعة، وثبّت مراجعة أو بصمة غير قابلة للتغيير، وحل المراجع في عزل مع حدود للوقت والتكرار والعمق والحجم.
امنع SSRF بحظر loopback والشبكات الخاصة وlink-local وواجهات بيانات المضيف والخدمات الداخلية بعد DNS. أعد التحقق عند كل تحويل، وحدد عدد التحويلات، وارفض الروابط الحاملة للاعتماد، ولا تمرر اعتماد المستودع أو API إلى أصل جديد.
احفظ ملفًا محلولًا مع الإصدار حتى لا يتغير ملف بعيد مستقلًا عنه. امنع النشر عند الدورات أو الحجم المفرط أو عنوان أساس ملتبس أو تحويل غير معتمد أو تغير البصمة.
اعرض الطلبات والردود بأمان
اهرب نصوص الرد وأوصاف المخطط قبل العرض. عامل HTML وSVG وMarkdown وقيم الأمثلة ورسائل الخطأ كمدخل غير موثوق. حدد حجم النص واقطعه مع إشعار واضح، ولا تنفذ شيفرة عائدة داخل أصل التوثيق.
احذف الاعتماد من أمثلة curl المنسوخة ولقطات أدوات المتصفح والتحليلات وحزم الدعم. يمكن لقياس يحترم الخصوصية تسجيل معرف العملية وفئة الحالة ونطاق الزمن وإصدار التوثيق وفئة الخطأ من دون نصوص أو رموز.
اختبر RTL ومحتوى API مختلط الاتجاه
في الصفحة العربية، تحقق من RTL للواجهة مع بقاء طرق HTTP والمسارات وJSON والشيفرة وUUID والطوابع الزمنية معزولة ومقروءة باتجاه LTR. اختبر المسارات الطويلة والمخططات المتداخلة وجداول القيم وعلامات التبويب ومحرر الطلب والشيفرة المنسوخة وأخطاء التحقق والتمرير الأفقي على الهاتف.
يجب ألا تعكس التسميات العربية علامات الترقيم داخل المسار أو تغير البايتات المنسوخة. قارن الطلب المنسوخ من الصفحتين الإنجليزية والعربية؛ يمكن للغة تغيير الشرح، لا الطريقة أو الرابط أو أسماء الترويسات أو معنى الحمولة.
انشر عبر بوابة قابلة للتنفيذ
قبل الإصدار، شغّل عمليات قراءة وخطأ تحقق وطلب موثق واعتماد منته وطلب تمهيدي وتحويل وتحديد معدل وعملية ذات أثر من متصفح مكتبي وهاتف. كرر لكل إصدار ولغة مدعومين، إضافة إلى اختبارات عقد سطر الأوامر.
امنع الإصدار عند وجود سر إنتاج في أصول العميل أو نطاق اعتماد واسع أو CORS مع اعتماد وأصل نجمي أو عدم تطابق الإصدار والخادم أو مرجع خارجي خطر أو رد غير مهرب أو فساد النسخ العربي. إذا تعذر تفعيل التجربة بأمان لعملية، فاترك المرجع وعطّل التنفيذ مع سبب دقيق.
ما الذي تتحقق منه بعد ذلك؟
اختر عملية آمنة وأخرى تغيّر الحالة. التقط نتيجة المتصفح وcurl على المؤسسة التجريبية، ودوّر الاعتماد، وبدّل إصدار التوثيق، وأبطل الذاكرة المؤقتة، ثم كرر بالإنجليزية والعربية. هذه الأدلة هي الحد الأدنى المفيد لقبول الوحدة.
المصادر وتاريخ المراجعة
رُوجعت المصادر في 2026-09-03: