Swagger UI هو أداة تتيح لك عرض وثائق API المُنشأة وفقاً لمواصفات Swagger (OpenAPI Specification). يوفر Swagger UI أيضًا إصدارات غير متصلة بالإنترنت وعبر الإنترنت لك، ولكن لأسباب مختلفة، قد تحتاج إلى فتح ملف مواصفات Swagger المُنشأ مع Swagger UI محليًا. في هذه المقالة، سنوضح لك كيفية تشغيل Swagger UI محليًا، إذا واجهت أي مشكلة في هذه العملية، تابع معنا.
ما هو Swagger UI؟
Swagger UI هو أداة تتيح لك عرض والتحقق من تعريفات API المكتوبة وفقًا لمواصفات OpenAPI (المعروفة سابقًا بمواصفات Swagger). من خلال إعداد Swagger UI في بيئة محلية واستيراد تعريف API، يمكن للمطورين التطوير مع التحقق من مواصفات API في الوقت الفعلي.
لماذا استخدام Swagger UI محليًا؟
بينما يقدم Swagger UI إصدار SaaS، يفضل العديد من المستخدمين تثبيته على أجهزتهم المحلية وإعداد خادم ويب محلي. وبالتالي، فإن العديد من المستخدمين يصلون إلى Swagger UI على localhost الخاص بهم. إذن، ما هي مزايا استخدام Swagger UI محليًا؟ دعنا نستكشف هذه الفوائد بالتفصيل.
تشمل الأسباب الرئيسية لاستخدام Swagger UI في بيئة محلية ما يلي:
- تطوير API في الوقت الحقيقي: عند تطوير API محليًا، من الضروري أن تكون لديك القدرة على التحقق من تعريف API في الوقت الفعلي.
- مرجع وثائق غير متصل بالإنترنت: يسمح الاستخدام المحلي لك بالرجوع إلى وثائق API غير المتصلة بالإنترنت، مما يلغي الحاجة إلى اتصال الشبكة.
- خصوصية معززة: يضمن الاستخدام المحلي أن تظل واجهة برمجة التطبيقات قيد التطوير خاصة، دون الحاجة إلى نشرها خارجيًا، مما يحافظ عليها بعيدة عن الوصول من الأطراف الثالثة.
- اختبار خادم تقليدي: يمكنك إعداد واختبار خادم تقليدي محلي للتحقق من وظيفة API الخاصة بك.
- تعريف API تدريجي: يتيح لك الاستخدام المحلي إجراء تغييرات تدريجية على تعريف API والتحقق من تأثيرها في كل مرة.
- تحقق من خط أنابيب CI/CD: يصبح التحقق المحلي جزءًا من خط أنابيب CI/CD الخاص بك، مما يضمن موثوقية وجودة API الخاصة بك أثناء التطوير.
مزايا استخدام Swagger UI محليًا
تُدرج مزايا استخدام Swagger UI في بيئة محلية أدناه، ولكن من الأفضل أن تقرر ما إذا كنت ستستخدم خدمة معتمدة على السحابة أو استخدامها محليًا اعتمادًا على الوضع المحدد.
- يمكن استخدامه دون اتصال لأنه لا يعتمد على بيئة الإنترنت
- تطوير سهل لأنك يمكنك التحقق من تعريفات API المحلية في الوقت الحقيقي
- لا حاجة لكشف الواجهة تحت التطوير للعالم الخارجي.
- يمكنك إعداد خادم تقليدي محليًا، لذا يمكنك التحقق من التشغيل.
- الاستجابة سريعة لأنها لا تعتمد على مواصفات جهاز التطوير.
- زيادة الإنتاجية من خلال التطوير وفقًا لسرعتك الخاصة
- أكثر أمانًا من استخدام خادم مشترك
- سهل لمزامنة تعريف API والتنفيذ
كيفية استخدام Swagger UI محليًا؟
ماذا يجب أن أفعل إذا كنت أرغب في استخدام Swagger UI محليًا؟ بعد ذلك، سأشرح بالتفصيل كيفية استخدام Swagger UI محليًا.
تثبيت Swagger UI وإعداد بيئة التطوير
أولاً، تحتاج إلى تنزيل Swagger UI وتثبيته على جهازك المحلي. يفضل استخدام الإصدار الأحدث. يتم إدارة مستودع Swagger UI على GitHub، لذا يرجى تثبيته باستخدام الأمر التالي.
git clone https://github.com/swagger-api/swagger-ui.git
ثم قم بإعداد بيئة التطوير الخاصة بك باستخدام أوامر مثل:
cd swagger-ui
npm run dev
سيتم إطلاق Swagger UI من خلال الوصول إلى http://localhost:3200/ في متصفحك.
إعداد خادم ويب محلي
بعد ذلك، لإطلاق Swagger UI، تحتاج إلى إعداد خادم ويب باستخدام سطر الأوامر التالي. هنا سنستخدم وحدة http-server الخاصة بـ Node.js.
npm install -g http-server
بدء خادم HTTP وإطلاق Swagger UI
انتقل إلى الدليل حيث يوجد ملف مواصفات Swagger، وأبدأ http-server في ذلك الدليل، وفعّل CORS باستخدام أمر مثل التالي:
cd {your-oas-document-dir}
http-server --cors
ثم، عندما تصل إلى http://localhost``:8080 في متصفحك، سيتم إطلاق Swagger UI.
إعداد ملف مواصفات Swagger
بعد ذلك، يجب إعداد ملف مواصفات Swagger. بشكل عام، تُكتب ملفات مواصفات Swagger بتنسيق Json أو Yaml. على سبيل المثال، افترض أنك كتبت ملفًا يسمى swagger.yaml. عنوان URL لملف المواصفات الخاص بـ Swagger هو http://localhost:8080/swagger.yaml.
أيضًا، إذا كنت ترغب في معرفة المزيد عن ملفات Swagger Spec أو تغيير المسار الافتراضي لعنوان URL الخاص بـ Swagger UI، يرجى الرجوع إلى المقالات التالية:
أدخل عنوان URL لملف مواصفات Swagger وافتحه في Swagger UI
ثم، على شاشة Swagger UI، أدخل عنوان URL الخاص بـ swagger.yaml في صندوق الإدخال في الأعلى، وانقر على زر الاستكشاف لعرض وثيقة تعريف API المحلية.
Apidog: إدارة واجهات برمجة التطبيقات الخاصة بك بكفاءة أكبر
عند استخدام Swagger UI، تحتاج إلى بناء خادم وتعيين عنوان URL، وهو أمر قد يكون مزعجًا نوعًا ما. إذا كنت تبحث عن حل أسهل، نوصي باستخدام Apidog، أداة إدارة API سهلة الاستخدام.
Apidog يمكنه قراءة ملفات Swagger Json و YAML مباشرة واختبار API الخاص بك بسرعة. يمكنك أيضًا استخدام خاصية المشاركة لإنشاء ومشاركة وثائق API جميلة.
استيراد JSON و YAML بسهولة في Apidog
يدعم Apidog استيراد البيانات بتنسيق YAML و JSON، بحيث يمكنك تحليل هذه الملفات بالكامل واستيراد بيانات API الخاصة بك بالكامل إلى Apidog للاختبار.
افتح إعدادات مشروعك في Apidog، انقر على استيراد البيانات، اختر OpenAPI/Swagger، واسحب ملف YAML إلى Apidog.
اختبر واجهة برمجة التطبيقات الخاصة بك باستخدام Apidog
بمجرد استيراد بيانات واجهة برمجة التطبيقات الخاصة بك إلى Apidog، يمكنك عرض واجهة برمجة التطبيقات المستوردة من خلال النقر على علامة التبويب APIs على اليسار. إذا كنت ترغب في اختبار نقطة نهاية API معينة، يمكنك النقر عليها، وملء المعلمات في واجهة مستخدم بديهية، "إرسال" الطلب، ثم الحصول على الاستجابة.
توليد ومشاركة وثائق API أسهل جدًا باستخدام Apidog. فيما يلي نموذج لوثائق API التي تم توليدها بواسطة Apidog:
الأسئلة الشائعة حول Swagger UI على localhost
كيف يمكن الوصول إلى Swagger UI على localhost؟
- قم بتشغيل مشروع API محليًا، ثم انتقل إلى
http://localhost``:<port>/swaggerفي متصفحك. المنفذ عادة هو 5000 أو 5001.
ما هو عنوان URL لخادم Swagger المحلي؟
- عنوان URL الافتراضي هو http://localhost:/swagger حيث المنفذ الذي تعمل عليه واجهة برمجة التطبيقات الخاصة بك محليًا.
كيف تستضيف وثائق Swagger محليًا؟
- قم بتمكين Swagger في كود بدء التشغيل الخاص بك، أطلق مشروع API، وانتقل إلى نقطة النهاية /swagger لعرض واجهة المستخدم.
ما هو عنوان URL الخاص بـ Swagger لـ localhost .NET core؟
- بالنسبة لواجهات برمجة التطبيقات .NET Core، يكون عنوان URL الخاص بـ Swagger عادةً http://localhost:/swagger/v1/swagger.json
ملخص
Swagger UI هي أداة مفيدة عند تطوير واجهات برمجة التطبيقات، ولكن لديها قيود لإدارة دورة حياة API الأكثر تقدمًا. يوفر Apidog وظائف شاملة لتطوير واجهات برمجة التطبيقات، مثل تعريف API، وتوليد الوثائق تلقائيًا، والاختبار، والمراقبة، والمشاركة.
يسمح لك Apidog باستيراد ملفات مواصفات Swagger و OpenAPI واختبار واجهة برمجة التطبيقات الخاصة بك بشكل تفاعلي. تسمح ميزات المشاركة لك بإنشاء وثائق جميلة ومشاركتها مع فريقك. إذا كنت ترغب في تبسيط عملية تطوير واجهة برمجة التطبيقات الخاصة بك، فإن Apidog هو الحل المناسب لك. باستخدامه جنبًا إلى جنب مع Swagger UI، ستكون قادرًا على تحقيق إدارة الدورة الحياتية لواجهة برمجة التطبيقات بشكل أكثر قوة.