تدقيق OpenAPI باستخدام Spectral بالإضافة إلى طريقة أسهل

يقوم مهندسان من نفس الفريق بشحن نقطتي نهاية في نفس الأسبوع. أحدهما يعيد created_at، والآخر يعيد createdAt. أحدهما يستخدم الترحيل بواسطة ?page=، والآخر بواسطة ?offset=. لا يوجد خطأ في أي منهما بمفرده. ولكن معًا، يجعلان واجهة برمجة التطبيقات (API) الخاصة بك تبدو وكأنها تم تجميعها بواسطة غرباء، ويدفع كل عميل يستهلكها ثمن ذلك. ملف OpenAPI يتحقق بشكل جيد. يتم تحليله، ويتم عرضه في Swagger UI، ويقوم بإنشاء حزمة SDK. إنه غير متناسق فحسب، ومدقق بسيط ليس لديه ما يقوله عن ذلك.

هذه هي الفجوة الدقيقة التي يسدها مدقق الأنماط (linter). المدقق يجيب على سؤال "هل هذا المواصفة متوافقة قانونيًا مع OpenAPI؟" بينما مدقق الأنماط يجيب على سؤال "هل تتبع هذه المواصفة القواعد التي اتفقنا عليها؟" الأداة مفتوحة المصدر الأكثر شيوعًا للسؤال الثاني هي Spectral، وهي أداة تدقيق الأنماط من Stoplight لمستندات JSON و YAML. تأتي مع مجموعة قواعد OpenAPI مدمجة، وتتيح لك كتابة قواعدك الخاصة، وتعمل من الطرفية أو محرر الأكواد الخاص بك. إذا كنت تريد طريقة مجانية وقابلة للبرمجة لفرض دليل نمط لواجهة برمجة التطبيقات (API)، فإن Spectral هو الخيار الأول الواضح، ويوضح لك هذا الدليل كيفية استخدامه بشكل صحيح.

كما يوضح لك المقايضة. Spectral عبارة عن مجموعة قواعد تقوم بتجميعها وصيانتها. للفرق التي تفضل الحصول على فحوصات التناسق، والخوادم الوهمية (mock servers)، والاختبارات القابلة للتشغيل من مكان واحد دون كتابة قواعد YAML يدويًا، يقوم Apidog بدمج هذا العمل في واجهة التصميم نفسها. سنثني على Spectral أولاً بشكل كامل، ثم نوضح أين يوفر لك المسار الشامل عناء الصيانة.

ما يفعله Spectral بالفعل

Spectral هو مدقق أنماط عام. توجهه إلى مستند منظم، وتعطيه مجموعة من القواعد، وهو يقوم بالإبلاغ عن كل مكان يخرق فيه المستند قاعدة ما، مع رقم السطر ومستوى الخطورة. إنه ليس خاصًا بـ OpenAPI؛ فهو يفهم OpenAPI و AsyncAPI و Arazzo فورًا، ويمكنك تدقيق أي ملف JSON أو YAML بقواعد مخصصة.

السبب الذي يجعله مهمًا لعمل واجهة برمجة التطبيقات هو مجموعة القواعد المدمجة spectral:oas. تُكود هذه المجموعة قائمة طويلة من اصطلاحات OpenAPI: يجب أن تحتوي العمليات على operationId، ويجب أن يحتوي كائن info على وصف ومعلومات اتصال، ويجب تعريف العلامات قبل استخدامها، ويجب ألا تتكرر المعاملات. قم بتشغيله على مواصفة حقيقية وستحصل دائمًا تقريبًا على قائمة تحذيرات في المحاولة الأولى. لا شيء منها يكسر المحلل اللغوي. جميعها تجعل التعامل مع المواصفة أصعب.

هذه مهمة مختلفة عن التحقق الهيكلي. أداة مثل swagger-cli أو Redocly تجيب على ما إذا كان المستند يتوافق مع مخطط OpenAPI. Spectral يجيب على ما إذا كان المستند يتبع نمط مؤسستك بالإضافة إلى ذلك. أنت تريد كليهما، وتتكامل الفحصين بشكل نظيف في خط أنابيب. ننتقل إلى نصف التحقق في الدليل حول كيفية التحقق من مواصفات OpenAPI؛ هذه المقالة تدور حول نصف النمط والاتساق.

تثبيت Spectral وتشغيل أول تدقيق أنماط لك

يأتي Spectral كحزمة npm. واجهة سطر الأوامر (CLI) هي @stoplight/spectral-cli. قم بتثبيته عالميًا:

npm install -g @stoplight/spectral-cli

Node.js هو الاعتماد الوحيد للنظام، لذا فإن أي جهاز أو صورة CI مثبت عليها Node بالفعل يمكنها تشغيله. إذا كنت تفضل عدم تثبيته عالميًا، فإن npx @stoplight/spectral-cli ... يعمل على مشغلي البناء المؤقتين.

يحتاج Spectral إلى مجموعة قواعد لمعرفة ما يجب التحقق منه. التقليد هو ملف يسمى .spectral.yaml في دليل العمل الخاص بك. أصغر ملف مفيد يوسع قواعد OpenAPI المضمنة:

# .spectral.yaml
extends: ["spectral:oas"]

الآن قم بتدقيق مواصفة. مع وجود ملف .spectral.yaml في الدليل الحالي، يلتقطه Spectral تلقائيًا:

spectral lint openapi.yaml

أو قم بالإشارة إلى مجموعة قواعد صراحةً:

spectral lint openapi.yaml --ruleset .spectral.yaml

الناتج قابل للقراءة عن قصد. يوضح كل اكتشاف السطر والعمود، مستوى الخطورة، القاعدة التي تم تفعيلها، ورسالة مفهومة للبشر:

openapi.yaml
  3:6   warning  info-contact      Info object should contain `contact` object.
  5:10  error    info-description   OpenAPI object info `description` must be present.

✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)

تلك الجولة الأولى ضد مواصفة موجودة هي اللحظة التي تدرك فيها معظم الفرق مدى الانحراف الذي تسلل. لم يتم فرض القواعد أبدًا، لذلك لم يتبعها أحد.

كتابة قواعدك الخاصة

مجموعة القواعد المدمجة هي نقطة بداية، وليست الوجهة النهائية. القيمة الحقيقية لـ Spectral هي ترميز اصطلاحات فريقك كقواعد يتحقق منها الجهاز في كل تغيير. تتكون القاعدة من أربعة أجزاء متحركة: ما يجب البحث عنه (given، تعبير JSONPath)، وما يجب التحقق منه (then، دالة)، ومدى وضوح الإبلاغ (severity)، وماذا يقال عند الفشل (message).

إليك قاعدة تفرض مسارات kebab-case، وهي اتفاقية شائعة في المؤسسات:

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Paths should be kebab-case.
    message: "{{property}} should be kebab-case (lower-case, hyphen-separated)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

يحدد given كل مفتاح مسار. تقوم الدالة then بتشغيل الدالة المدمجة pattern مقابل تعبير عادي. أي شيء يفشل في هذا النمط يتم الإبلاغ عنه كتحذير مع رسالتك. يمكنك حظر معرفات الأرقام الصحيحة لصالح UUIDs، أو طلب استجابة خطأ في كل طلب POST، أو منع أرقام الإصدارات في عناوين URL للخادم، أو طلب أن تحمل كل عملية وصفًا. يقدم Spectral العديد من الوظائف الأساسية (truthy، pattern، schema، length، enumeration، والمزيد) لذا فإن معظم الاصطلاحات لا تتطلب أي كود على الإطلاق.

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

الخطورة، وجعل البناء يفشل

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

بمجرد أن تكون مواصفتك نظيفة، أحكم الإغلاق. يتحكم علم --fail-severity في العتبة:

spectral lint openapi.yaml --fail-severity=warn

الآن يعيد التحذير أيضًا رمز الخروج 1، وهو ما تقرأه خطوة التكامل المستمر (CI) لتمييز نفسها بالفشل. هذه هي الآلية التي تحول مدقق الأنماط إلى بوابة جودة حقيقية: يمنع خط الأنابيب الدمج في اللحظة التي تنحرف فيها المواصفة عن دليل الأنماط. يمكنك أيضًا تجاوز مستويات خطورة القواعد الفردية في مجموعة القواعد الخاصة بك، عن طريق رفع قاعدة تهتم بها من warn إلى error أو إسكات قاعدة لا تتناسب مع فريقك بتعيينها إلى off.

تشغيل Spectral في CI

مدقق الأنماط الذي يعمل فقط عندما يتذكره أحدهم ليس بوابة. الهدف هو تشغيله عند كل عملية دفع (push)، على جهاز نظيف، بنفس مجموعة القواعد للجميع. Spectral يجعل هذا الأمر بسيطًا. إليك مهمة GitHub Actions تقوم بتدقيق المواصفة في أي طلب سحب (pull request) يمسها:

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi.yaml --fail-severity=warn

لتقارير أكثر ثراءً، يمكن لـ Spectral إصدار JUnit XML، والذي تحلله معظم لوحات تحكم CI إلى شجرة نجاح/فشل:

spectral lint openapi.yaml -f junit -o results.xml

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

حيث يطلب Spectral الكثير منك

Spectral جيد فيما يفعله. ولكن الصيد الحقيقي هو أنه يقوم بشيء واحد، والبقية من دورة حياة المواصفة هي مشكلتك لتجميعها. تظهر بعض الحقائق بمجرد أن يتبناه فريق بعد العرض التوضيحي.

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

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

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

لا شيء من هذا ينتقص من Spectral. إنه مدقق أنماط مركز وهو صريح بشأن نطاقه. ولكن "التركيز" يعني أن عمل التكامل يقع على عاتقك.

الطريقة الأسهل: الاتساق مدمج في واجهة التصميم

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

Apidog هو منصة شاملة لواجهة برمجة التطبيقات: تقوم بتصميم المخطط، وتصحيح الأخطاء في الطلبات، وبناء سيناريوهات الاختبار، ونقاط نهاية وهمية (mock endpoints)، ونشر الوثائق في مساحة عمل واحدة. ولأن التصميم يحدث داخل الأداة، فإن فحوصات الاتساق تحدث أثناء الكتابة. يبرز المصمم المرئي المشكلات الهيكلية لحظة ظهورها، بالطريقة التي يشير بها المترجم إلى خطأ في بناء الجملة، لذلك تقوم بإصلاحها قبل أن تصل إلى أي التزام. أنت لا تشغل مدقق أنماط منفصل بعد الحقيقة؛ المحرر هو مدقق الأنماط.

الفرق الأكبر هو كل شيء لاحق. يصبح نفس العقد الذي تصممه خادمًا وهميًا لك (mock server)، ووثائقك التفاعلية، وسيناريوهات اختبارك، دون إعادة تحليل ودون الحاجة إلى أداة ثانية للحفاظ على التزامن. عندما تريد هذه الفحوصات في خط أنابيب، تقوم واجهة سطر الأوامر Apidog CLI بتشغيل سيناريوهات الاختبار الخاصة بك دون واجهة رسومية من الطرفية وتخرج برمز غير صفري عند الفشل، تمامًا سلوك البوابة الذي أردته من مدقق الأنماط، باستثناء أنه يختبر واجهة برمجة التطبيقات قيد التشغيل مقابل العقد بدلاً من مجرد قراءة الملف. قم بتثبيته بأمر npm واحد ووجهه إلى سيناريو:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli

هذا يسد الفجوة التي يتركها Spectral مفتوحة. يؤكد Spectral أن المستند يتبع نمطك. بينما تؤكد واجهة سطر الأوامر Apidog CLI أن التنفيذ لا يزال يتطابق مع المستند. للاطلاع على مرجع العلامات الكامل، قم بتشغيل apidog run --help أو اقرأ دليل واجهة سطر الأوامر الكامل.

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

نظرة سريعة على Spectral مقابل Apidog

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

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

هل Spectral مجاني؟ نعم. Spectral مفتوح المصدر بموجب ترخيص Apache 2.0، ويتم صيانته بواسطة Stoplight. واجهة سطر الأوامر، ومجموعة قواعد OpenAPI المدمجة، وتأليف القواعد المخصصة كلها مجانية للاستخدام.

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

هل يمكن لـ Spectral اختبار واجهة برمجة التطبيقات (API) الخاصة بي قيد التشغيل؟ لا. يقرأ Spectral ملف المواصفة فقط. للتحقق من أن واجهة برمجة التطبيقات المباشرة تتطابق مع العقد، تحتاج إلى مشغل يرسل طلبات حقيقية ويتأكد من الاستجابات، مثل Apidog CLI.

كيف أجعل تحذير Spectral يفشل بناء CI الخاص بي؟ قم بتشغيل spectral lint openapi.yaml --fail-severity=warn. افتراضيًا، يفشل البناء فقط عند مستوى الخطورة error؛ أما --fail-severity=warn فيجعل التحذيرات تعيد رمز خروج غير صفري أيضًا.

ما الفرق بين Spectral و Apidog؟ Spectral هو مدقق أنماط مفتوح المصدر ومركز تقوم بتكوينه وصيانته. Apidog عبارة عن منصة شاملة حيث يعيش التصميم، وفحوصات الاتساق، والمحاكاة، والوثائق، والاختبارات معًا، وبالتالي تقوم بتجميع أقل وتحافظ على تزامن أقل. راجع Apidog vs Swagger لمقارنة ذات صلة بمشهد أدوات التصميم.

الخلاصة

يحل Spectral مشكلة حقيقية تتجاهلها أدوات التحقق البسيطة: الحفاظ على اتساق مواصفات OpenAPI مع الاصطلاحات التي اتفق عليها فريقك. قم بتثبيت @stoplight/spectral-cli، وقم بتوسيع spectral:oas، وأضف بعض القواعد المخصصة، وقم بتحصين خط الأنابيب الخاص بك باستخدام --fail-severity=warn. بالنسبة للعديد من الفرق، هذا يكفي، ولا يكلف شيئًا.

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