صمم أولاً باستخدام محرر سواجر: الأداة النهائية لواجهة برمجة التطبيقات

Swagger هي أداة شائعة لتطوير واجهات البرمجة التطبيقات (API) تساعد المطورين على تصميم وبناء واختبار واجهات البرمجة RESTful بسرعة. يقدم الموقع الرسمي لSwagger العديد من الأدوات والمكتبات، من بينها Swagger Editor التي تُعد أداة مفيدة بشكل خاص تساعد المطورين على إنشاء وتحرير ملفات مواصفات Swagger. ستقدم هذه المقالة أساسيات واستخدامات Swagger Editor.

فوائد استخدام Swagger Editor

Swagger Editor هي أداة مفتوحة المصدر لكتابة واختبار مواصفات OpenAPI، مع المزايا التالية:

كتابة واختبار مواصفات OpenAPI: تسمح Swagger Editor للمطورين بكتابة مواصفات OpenAPI في محرر بصري واختبار الوظائف والاستجابة لهذه المواصفات على نفس الواجهة على الفور.
الإكمال التلقائي والتحقق من الأخطاء: يمكن أن تساعد Swagger Editor المطورين في إكمال الكلمات الرئيسية والمعلمات تلقائيًا عند كتابة مواصفات OpenAPI، وتقديم تحقق من الأخطاء في الوقت الحقيقي لتجنب الأخطاء النحوية الشائعة وأخطاء المواصفات.
التعاون السهل: تسمح Swagger Editor لعدة مطورين بالتعاون على نفس مواصفة OpenAPI، مما يجعل من الأسهل مشاركة ومناقشة مواصفات API داخل فريق التطوير.
التكامل مع أدوات Swagger الأخرى: يمكن دمج Swagger Editor مع أدوات Swagger الأخرى، مثل Swagger UI وSwagger Codegen، لتوفير حل شامل لتطوير واختبار API.

البدء مع Swagger Editor

تثبيت Swagger Editor

يمكن تثبيت وتشغيل Swagger Editor بطريقتين:

الاستخدام عبر الإنترنت: تقدم Swagger إصدارًا عبر الإنترنت من Swagger Editor على موقعها، والذي يمكن استخدامه ببساطة عن طريق زيارة الموقع. لا تتطلب هذه الطريقة أي تثبيت ويمكن استخدامها مباشرة.
التثبيت المحلي: تقدم Swagger أيضًا إصدارًا محليًا من Swagger Editor على موقعها، والذي يمكن تنزيله من GitHub. بعد التنزيل، قم بفك ضغط الملفات وتشغيل الأمر التالي للبدء:

npm install
npm start

فهم واجهة مستخدم Swagger Editor

Swagger Editor هي أداة شهيرة لتصميم وبناء واختبار واجهات البرمجة RESTful. تقدم واجهة مستخدم سهلة الاستخدام تتيح للمطورين كتابة واختبار مواصفات OpenAPI، مع ميزات مثل الإكمال التلقائي والتحقق من الأخطاء.

منطقة التحرير هي المكان المركزي لإنشاء وتحرير المواصفات، ويوفر اللوح الجانبي تنقلًا سهلاً بين أجزاء مختلفة من المواصفة. يعرض تبويب المعلومات معلومات عامة عن API، بينما يوفر تبويب المسارات قائمة بالنقاط النهاية. يسمح تبويب التعريفات للمطورين بإنشاء أو تحرير نماذج البيانات، ويوفر تبويب المعلمات قائمة بالمعلمات. يعرض تبويب الاستجابات قائمة بالاستجابات، ويحدد تبويب الأمان آليات المصادقة والتفويض لـ API.

كيفية استخدام Swagger Editor

بعد بدء تشغيل Swagger Editor، يمكنك البدء في إنشاء وتحرير ملفات مواصفات Swagger من خلال العمليات الأساسية التالية:

إنشاء ملف مواصفات Swagger جديد

عند بدء Swagger Editor، سيتم فتح ملف مواصفات Swagger فارغ تلقائيًا. لإنشاء ملف مواصفات Swagger جديد، انقر على زر "مستند جديد" في اليسار.

تعديل ملف مواصفات Swagger

في Swagger Editor، يمكنك بسهولة تعديل ملفات مواصفات Swagger. يعرض اللوح الأيسر الهيكل الشجري لملف مواصفات Swagger، بينما يعرض اللوح الأيمن الكود بتنسيق YAML المقابل. يمكنك تعديل الكود YAML المقابل عن طريق النقر المزدوج على أي عقدة في الهيكل الشجري للوح الأيسر. بعد التحرير، يمكنك النقر على زر "التحقق" في الزاوية العلوية اليسرى للتحقق مما إذا كان الكود يتوافق مع مواصفة Swagger.

معاينة وثائق Swagger

في Swagger Editor، يمكنك بسهولة معاينة وثائق Swagger. من خلال النقر على زر "معاينة" على اليسار، يمكنك عرض تأثير المعاينة لوثائق Swagger في نافذة المتصفح اليمنى. يمكنك اختبار واجهات API لـ Swagger وعرض النتائج المرجعة في نافذة المعاينة.

استيراد وتصدير ملفات مواصفات Swagger

في Swagger Editor، يمكنك بسهولة استيراد وتصدير ملفات مواصفات Swagger. يمكنك النقر على زر "ملف" في الزاوية العلوية اليسرى، ثم تحديد "استيراد URL" أو "استيراد ملف" لاستيراد ملف مواصفات Swagger. يمكنك أيضًا تحديد "تحميل كـ" لتصدير ملف مواصفات Swagger.

ميزات أخرى

بالإضافة إلى العمليات الأساسية والأساليب الموضحة أعلاه، يوفر Swagger Editor العديد من الميزات الأخرى، بما في ذلك:

الإكمال التلقائي وإبراز النحو;
دعم لمواصفات Swagger 2.0 وOpenAPI 3.0;
أنماط وقوالب قابلة للتخصيص;
دعم لعدة تنسيقات من المدخلات والمخرجات.

عن مواصفة OpenAPI

مواصفة OpenAPI (المعروفة أيضًا بمواصفة Swagger) هي معيار لوصف واجهات البرمجة RESTful. تحدد البيانات الوصفية مثل معلومات واجهة API، والمعلمات المطلوبة، وقيم الاستجابة، وتوفر دعمًا لأدوات الأتمتة. تم اقتراح مواصفة OpenAPI في الأصل بواسطة Swagger وأصبحت الآن معيارًا مفتوحًا بدعم من العديد من الشركات والمنظمات.

يمكن أن تساعد مواصفة OpenAPI المطورين والفرق على تصميم وكتابة واختبار واجهات البرمجة RESTful بشكل أكثر فعالية مع تحسين قابلية القراءة والصيانة. تشمل الميزات الرئيسية لمواصفة OpenAPI ما يلي:

لغة الوصف: تستخدم مواصفة OpenAPI YAML أو JSON وغيرها من لغات الوصف لوصف معلومات واجهة API. ويمكنها تحديد مسارات API، والمعلمات، وأجسام الطلبات، والاستجابات، وأكواد الأخطاء.
وثائق بصرية: يمكن أن تولد مواصفة OpenAPI وثائق API بصرية تدعم الاختبار والتصحيح عبر الإنترنت.
قابلية التوسيع: تدعم مواصفة OpenAPI خصائص مخصصة وامتدادات لتلبية احتياجات الأعمال المختلفة.
دعم عبر اللغات: يمكن دعم مواصفة OpenAPI بواسطة أدوات توليد الكود في لغات مختلفة، مثل Java وNode.js وPython وGo.

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

كتابة Swagger بالكود

إذا كان المطورون قادرين على كتابة Swagger بالكود، خاصة بـ VSCode. قد يكون ذلك أكثر فعالية لعدة أسباب:

توفير الوقت والكفاءة: يمكن أن يؤدي توليد Swagger من الكود إلى تقليل عبء العمل بشكل كبير عند كتابة Swagger يدويًا، خاصة للمشاريع الكبيرة، والتي قد تستغرق أيامًا أو أسابيع لإكمالها يدويًا ولكن يمكن توليدها في دقائق من خلال أدوات الأتمتة.
توثيق أكثر دقة: يمكن أن يضمن توليد Swagger من الكود التناسق بين وثائق Swagger والكود الفعلي، مما يتجنب الحالات التي تكون فيها الوثائق والكود غير متزامنين ويجعل وثائق API أكثر دقة.
سهول الصيانة: يمكن أن يجعل توليد Swagger من الكود صيانة API أسهل لأن وثائق Swagger والكود متناسقان. عندما تحدث تغييرات في API، يحتاج فقط الكود إلى التحديث، وسيتم تحديث وثائق Swagger تلقائيًا، مما يقلل من صعوبة العمل الصيانة.
إعادة استخدام أفضل: يمكن أن يجعل توليد Swagger من الكود وثائق Swagger المولدة أكثر قابلية لإعادة الاستخدام لأن وثائق Swagger تحتوي على معلومات مفصلة حول API، والتي يمكن إعادة استخدامها بواسطة مطورين آخرين أو مختبرين أو عملاء API، مما يقلل من الوقت والجهد المستهلك في الأعمال الزائدة.

اختيار أفضل من Swagger Editor

لفرق Design First، يُعتبر Apidog أداة تصميم واجهة برمجة تطبيقات متقدمة تُوصى بشدة. طالما أننا على دراية بهيكل JSON، يمكنك إتقان سر تصميم واجهات البرمجة في Apidog. Apidog هو عبارة عن مجموعة من Postman وSwagger وMock وJMeter.

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