مقدمة
Swagger إطار عمل قوي ومرن لتصميم وبناء وتوثيق واستخدام واجهات برمجة تطبيقات الويب. يساعد المطورين وفرق تطوير البرمجيات على تبسيط عملية تطوير واجهات برمجة التطبيقات. يعتمد Swagger على معيار OpenAPI، ويتيح لك كتابة وصف مفصل لواجهة برمجة التطبيقات، بما في ذلك المسارات والمدخلات والمخرجات وأنواع البيانات.
لماذا يجب علينا استخدام Swagger؟
يوصى باستخدام Swagger لعدة أسباب:
- التوثيق التلقائي: يتيح لك Swagger إنتاج وثائق دقيقة وقابلة للقراءة لواجهات برمجة التطبيقات الخاصة بك والتي يمكن تحديثها بسهولة.
- الاختبار واستكشاف الأخطاء وإصلاحها: تتيح لك واجهة Swagger التفاعلية اختبار واجهات برمجة التطبيقات مباشرة في المتصفح وفحص الاستجابات.
- التوحيد القياسي: من خلال استخدام معيار OpenAPI، ستكون واجهات برمجة التطبيقات الخاصة بك متوافقة مع أدوات ولغات مختلفة.
- زيادة التعاون: تتيح الوثائق الدقيقة والموحدة لفرق التطوير المختلفة التعاون بشكل أفضل.
هيكل التوثيق في Swagger
عادةً ما تُكتب وثائق Swagger كملف YAML أو JSON. يحتوي هذا الملف على أقسام متنوعة تُساعد في وصف واجهة برمجة التطبيقات (API) بشكل كامل:
- معلومات: معلومات عامة حول واجهة برمجة التطبيقات مثل الاسم والوصف والإصدار.
- المسارات: مسارات HTTP والطرق المرتبطة بكل مسار.
- عناصر: تعريف أنواع البيانات والأخطاء والنماذج الشائعة.
مثال على ملف Swagger بتنسيق YAML
فيما يلي مثال بسيط لتوثيق Swagger:
openapi: 3.0.0 info: title: Sample API version: 1.0.0 paths: /users: get: summary: الحصول على قائمة بالمستخدمين description: تُرجع هذه الطريقة قائمة بالمستخدمين. responses: '200': description: successful content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string
عرض وثائق Swagger في المتصفح
لعرض وثائق Swagger في المتصفح، يمكنك استخدام المكتبة واجهة مستخدم Swagger استخدم. الكود التالي يوضح كيفية القيام بذلك:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: 'https://petstore.swagger.io/v2/swagger.json',
dom_id: '#swagger-ui',
});
</script>
</body>
</html>أدوات متعلقة بـ Swagger
يحتوي Swagger على العديد من الأدوات، كل منها لها استخدام محدد خاص بها:
- محرر Swagger: أداة لكتابة وتحرير وثائق OpenAPI.
- واجهة مستخدم Swagger: أداة لعرض وثائق واجهة برمجة التطبيقات بشكل تفاعلي.
- Swagger Codegen: أداة لإنشاء كود العميل والخادم من وثائق OpenAPI.
- مركز سواغر: منصة للتعاون بين الفريق وإدارة واجهة برمجة التطبيقات.
خاتمة
Swagger أداة أساسية لأي مطور يعمل مع واجهات برمجة التطبيقات. يوفر مجموعة متنوعة من الميزات التي تُبسط عملية تصميم وتطوير وتوثيق واجهات برمجة التطبيقات، مما يُساعد فرق التطوير على العمل بشكل أفضل وأسرع. مع Swagger، يمكنك إنشاء واجهات برمجة تطبيقات موحدة وموثوقة وسهلة الاستخدام.
