أدوات CLI مجانية ومفتوحة المصدر لتصميم API

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

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

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

ملاحظة صريحة مقدمًا. Apidog مميز هنا، لكنه ليس مفتوح المصدر؛ إنه منتج تجاري مع طبقة مجانية، ولا يدقق مواصفاتك. لذا يحصل على ملاحظة جانبية دقيقة، وليس إدخالًا مفتوح المصدر. الأدوات أدناه هي سلسلة أدوات التصميم مفتوحة المصدر الحقيقية.

ما الذي يجعل أداة سطر الأوامر مفتوحة المصدر لتصميم واجهة برمجة التطبيقات

المصدر المفتوح هو ادعاء محدد، وليس مجرد شعور. لهذه القائمة، تتأهل الأداة عندما تتحقق ثلاثة أمور.

أولاً، الترخيص. يجب أن يكون ترخيصًا متساهلًا حقيقيًا أو ترخيصًا مشاعًا يمكنك قراءته؛ MIT و Apache-2.0 هما الاثنان اللذان ستراهما أكثر هنا. هذا ما يسمح لك باستخدام الأداة في مشروع تجاري دون رسوم ترخيص أو حساب مقاعد.

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

ثالثاً، الصيانة والمجتمع. مستودع به التزامات حديثة، ومشكلات مفتوحة تحصل على إجابات، وسجل تغييرات عام. يمكن أن يظل المشروع المهجور مرخصًا بـ MIT ولكنه لا يزال رهانًا سيئًا، لذلك أضع علامة على حالة الصيانة حيثما يهم.

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

Spectral: مدقق نمط OpenAPI المرن

Spectral من Stoplight هو مدقق النمط مفتوح المصدر المرجعي لأوصاف واجهة برمجة التطبيقات، ومرخص بموجب Apache-2.0. يقرأ مجموعة قواعد (ملف YAML أو JSON أو JavaScript يسرد قواعدك) ويطبقها على مستندات OpenAPI 3.x و OpenAPI 2.0 و AsyncAPI و Arazzo. إذا كان فريقك لديه دليل نمط API مكتوب، فإن Spectral هو كيف تجعله قابلاً للتنفيذ.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

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

الأفضل في: فرض دليل نمط فريق كرمز. الحد الصادق: يفحص Spectral مواصفات واحدة؛ لا يقارن بين نسختين، لذا قم بإقرانه بأداة فرق لالتقاط التغييرات الجذرية.

vacuum: أسرع مدقق نمط، بديل لمجموعات قواعد Spectral

إذا كان Spectral هو المعيار، فإن vacuum هو سرعة الأداء. إنه مدقق نمط Go، مرخص بـ MIT، ومتوافق بنسبة 100% مع مجموعات قواعد Spectral. لذلك يمكنك توجيهه إلى نفس مجموعة القواعد التي كتبتها بالفعل والحصول على نتائج أسرع بكثير على المواصفات الكبيرة، وهو بالضبط ما تريده في خطاف ما قبل الالتزام (pre-commit hook) أو حلقة CI ضيقة.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

تمنحك علامة -d إخراجًا تفصيليًا لكل قاعدة. يقوم vacuum أيضًا بأكثر من مجرد التدقيق؛ فهو يولد تقارير HTML ووثائق من نفس المواصفات. نظرًا لأنه ثنائي مجمع واحد بدون وقت تشغيل Node، فإنه يبدأ بسرعة ويسقط بسلاسة في حاوية.

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

Redocly CLI: تدقيق وتجميع في ثنائي واحد

Redocly CLI مرخص بـ MIT ويغطي مهمة مختلفة قليلاً. إنه يدقق، لكن أبرز ما فيه هو bundle: يأخذ مواصفات مقسمة عبر العديد من ملفات $ref (الطريقة المنطقية للحفاظ على تصميم API كبير قابل للصيانة) ويقوم بتسطيحها في مستند واحد للأدوات التي تتوقع ملفًا واحدًا. كما أنه يولد وثائق مرجعية لواجهة برمجة التطبيقات من النتيجة المجمعة.

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

تقسيم المواصفات الخاصة بك إلى ملفات لكل مورد يحافظ على سهولة قراءة الفروق وتقليل تعارضات الدمج، وهو أمر أساسي لسير عمل تصميم واجهة برمجة التطبيقات الأصلي لـ Git. تُعد bundle من Redocly هي الخطوة التي تحول هذا المصدر متعدد الملفات مرة أخرى إلى الأثر الفردي الذي تستهلكه CI أو خادم المحاكاة أو موقع المستندات الخاص بك.

الأفضل في: مشاريع المواصفات متعددة الملفات التي تحتاج إلى التجميع بالإضافة إلى تمريرة التحقق. الحد الصادق: قواعد التدقيق الافتراضية الخاصة به أخف من مجموعة قواعد Spectral مخصصة بالكامل، لذلك تقوم العديد من الفرق بتشغيل Redocly للتجميع و Spectral أو vacuum لفرض النمط العميق.

openapi-generator: حول التصميم إلى عملاء ومكونات وهمية ووثائق

لا يكتمل التصميم إلا بعد أن يتمكن الآخرون من البناء عليه. openapi-generator هو Apache-2.0 ويولد حزم تطوير البرامج للعملاء (SDKs)، ومكونات الخادم الوهمية (server stubs)، والوثائق من مواصفات OpenAPI عبر عشرات اللغات. اعتبار المواصفات مصدر الحقيقة وتوليد البقية هو جوهر نهج "المخطط أولاً" و "المدفوع بالعقد"، والذي نغطيه في مبادئ تصميم واجهة برمجة التطبيقات.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

استبدل -g typescript-axios بـ go أو python أو java أو kotlin أو أي من المولدات المدعومة العديدة. قم بتشغيله في CI عند كل تغيير في المواصفات، ولن تبتعد مكتبات العملاء الخاصة بك عن العقد أبدًا.

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

oasdiff: اكتشاف التغييرات الجذرية قبل أن تصل إلى العملاء

يخبرك المدقق ما إذا كانت المواصفات نظيفة. لا يمكنه إخبارك أن إعادة تسمية حقل ما قد عطلت كل عميل في الإنتاج. oasdiff هي أداة Go المرخصة بـ Apache-2.0 التي تملأ هذه الفجوة: أعطها نسختين من المواصفات وستقوم بالإبلاغ عن الفرق، وعلى وجه التحديد التغييرات الجذرية.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

يعرض الأمر breaking فقط التغييرات التي تعطل المستهلكين الحاليين؛ يمنحك changelog قائمة قابلة للقراءة البشرية بكل ما تغير، سواء كان جذريًا أم لا؛ يمنحك diff الفرق الكامل القابل للقراءة آليًا. قم بربط oasdiff breaking بفحص طلب السحب (pull-request) ويصبح التغيير الجذري بناءً فاشلاً بدلاً من صفحة الساعة 3 صباحًا.

الأفضل في: حماية التغييرات الجذرية في CI. الحد الصادق: يقارن المواصفات، لذا فإنه جيد بقدر انضباطك في الحفاظ على المواصفات محدثة مع واجهة برمجة التطبيقات الحقيقية. إنه لا يدقق النمط؛ استخدمه جنبًا إلى جنب مع Spectral أو vacuum.

Optic: فرق وتدقيق معًا، مع تحذير بشأن الصيانة

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

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

هذا هو الصدق الذي تدين به لك قائمة المصادر المفتوحة: تم أرشفة مستودع Optic العام في أوائل عام 2026 ولم يعد المشروع يُصان بشكل نشط. لا يزال مصدر MIT يعمل، لذا يمكنك تضمينه، لكنك لن تحصل على قواعد جديدة أو تصحيحات أمنية. للكشف عن التغييرات الجذرية اليوم، oasdiff هو الخيار الذي تتم صيانته؛ يبقى Optic في القائمة لأنك ستجده لا يزال مستخدمًا في خطوط الأنابيب الحالية.

الأفضل في: الفرق التي استثمرت فيه بالفعل، أو أي شخص يريد التدقيق والمقارنة في سطر أوامر واحد. الحد الصادق: لم يعد يُصان اعتبارًا من أوائل عام 2026؛ تعامل معه كتراث وقدّر مسار ترحيل.

أين يتناسب Apidog (وأين لا يتناسب)

Apidog ليس مفتوح المصدر، ولا يدقق OpenAPI الخاص بك أو يفرض قواعد النمط؛ Spectral و vacuum و Redocly هي أدوات التدقيق الخاصة بك، نقطة. ما يقدمه Apidog هو مقايضة مختلفة: بدلاً من ربط ستة ثنائيات منفصلة معًا، تمنحك طبقتها المجانية بالإضافة إلى ثنائي apidog-cli مكانًا متكاملاً لتصميم نقاط النهاية ومخططات البيانات، ثم تصدير النتيجة كـ OpenAPI لإعادة تغذيتها مباشرة إلى فحوصات المصدر المفتوح هذه.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

يحتوي CLI على مجموعات أوامر لـ endpoint و schema و mock و import/export، بحيث يمكنك برمجة تصميم واجهة برمجة التطبيقات من الطرفية وتسليم المواصفات المصدرة إلى openapi-generator أو oasdiff. راجع دليل Apidog CLI الكامل للحصول على مجموعة الأوامر الكاملة. الإطار الصادق: Apidog هو الخيار التجاري المتكامل الذي يعمل بشكل جيد مع سلسلة أدوات المصدر المفتوح، وليس بديلاً لمدقق النمط وليس مشروعًا مفتوح المصدر بحد ذاته.

كيف تختار

طابق الأداة بالمهمة. معظم الفرق تشغل اثنين أو ثلاثة من هذه الأدوات معًا، وليس أداة واحدة.

مجموعة أدوات عملية: Spectral أو vacuum للنمط، Redocly للتجميع، oasdiff للتغييرات الجذرية، و openapi-generator لإنتاج العملاء. إذا كانت صيانة هذا العدد الكبير من الأدوات أكثر مما ترغب في امتلاكه، فإن منصة متكاملة تغطي جزء التصميم والتصدير في مكان واحد. للحصول على نظرة أوسع للمشهد البرمجي بما يتجاوز CLI، راجع دليلنا حول بدائل Swagger لتصميم واختبار واجهة برمجة التطبيقات والأساسيات في كيفية تصميم واجهات برمجة تطبيقات REST.

الخلاصة

سلسلة أدوات سطر الأوامر مفتوحة المصدر لتصميم واجهة برمجة التطبيقات ناضجة ومجانية للتشغيل: Spectral و vacuum لتدقيق النمط، Redocly للتجميع، openapi-generator لإنتاج العملاء، و oasdiff للحماية من التغييرات الجذرية، مع Optic كخيار قديم يجب الاعتراف به. قم بربطها بـ CI ويتم فحص عقد واجهة برمجة التطبيقات الخاص بك في كل عملية دفع (push) بدون تكلفة لكل مقعد وبدون حصر البائع.

إذا كنت تفضل تصميم نقاط النهاية والمخططات في أداة متكاملة واحدة وتصدير OpenAPI نظيف إلى نفس خط الأنابيب هذا، قم بتنزيل Apidog وجرب apidog-cli؛ إنه الرفيق التجاري لمكدس المصدر المفتوح، وليس بديلاً لمدقق النمط الخاص بك. على أي حال، الهدف هو نفسه: اكتشاف مشاكل التصميم في الطرفية، قبل أن تصل إلى المستخدمين.