مدقّق OpenAPI
تحقق من مستند OpenAPI 3.0 أو 3.1 أو 3.2 أو Swagger 2.0 بصيغة YAML أو JSON، واحصل على ملخص لنقاط النهاية والمخططات. يتحقق المدقّق من الحقول المطلوبة، ومن مطابقة قوالب المسارات لمعاملات المسار، ومواقع المعاملات، ورموز الاستجابة، وتكرار معرّفات العمليات، وكل $ref محلي، كما يسرد كل مشكلة مع موضعها.
الأسئلة الشائعة
ما الذي يتحقق منه المدقق؟
يتحقق من إصدار openapi أو swagger، وinfo.title وinfo.version، ومن بدء المسارات بشرطة مائلة، ومن وجود معامل مسار مطلوب مطابق لكل {parameter} في المسار، والعكس. كما يتحقق من أسماء المعاملات ومواقعها، ورموز حالات الاستجابة وأوصافها، والمعاملات المكررة، وقيم operationId المكررة، ومن أن كل $ref محلي يشير إلى عنصر في المستند.
هل هذا تحقق كامل من صحة مواصفات مخطط JSON؟
لا. يتحقق من القواعد البنيوية المذكورة أعلاه، التي تكشف معظم الأخطاء في المستندات المكتوبة يدويًا، لكنه لا يتحقق من كل حقل وفق المخطط الفوقي الرسمي ولا من محتوى مخططاتك.
ما الذي يعرضه الملخص؟
المواصفة وإصدار API، والعنوان، وجدولًا بكل نقطة نهاية يتضمن طريقتها ومسارها وoperationId وملخصها ورموز الاستجابة، وأسماء المخططات ضمن components.schemas، أو التعريفات في Swagger 2.0.
هل تُتبع المراجع الخارجية؟
لا. لا تُجلب المراجع إلى ملفات أو عناوين URL أخرى ولا يُبلّغ عنها. تُحل داخل المستند الملصق المراجع التي تبدأ بـ # فقط.
ما الفرق بين الأخطاء والتحذيرات؟
تشير الأخطاء إلى مخالفة قاعدة من قواعد المواصفة، مثل غياب وصف الاستجابة أو عدم التصريح عن معامل مسار. أما التحذيرات فتشير إلى أمور مسموح بها لكنها غالبًا غير مقصودة، مثل عملية GET تتضمن متن طلب أو مستند لا يحتوي على أي operationId.
هل يغيّر OpenAPI 3.1 ما هو مطلوب؟
نعم. في OpenAPI 3.1 و3.2، لم تعد العملية بحاجة إلى كائن responses، ويمكن أن يحتوي المستند على webhooks أو components بدلًا من paths. يطبق المدقّق هذه القواعد عندما تبدأ قيمة الحقل openapi بـ 3.1 أو 3.2.