منسّق Swagger JSON

تعمل في المتصفح الويب

نسّق Swagger 2.0 JSON تنسيقاً أنيقاً، واكتشف إصدار المواصفة، واسرد نقاط النهاية والتعريفات، وحوّل إلى YAML.

الخصوصية: تعمل هذه الأداة بالكامل في متصفحك. لا تغادر بياناتك جهازك أبداً.

ما هو اختبار عقود API؟

عقد API هو الوصف المتفق عليه للواجهة — نقاط النهاية والمعاملات ومخططات الطلب والاستجابة ورموز الحالة — ويُكتب عادةً كمستند OpenAPI. اختبار العقد يقارن ما تعيده الخدمة فعلياً بذلك الوصف، فيُكشف الحقل المعاد تسميته أو النوع المتغيّر لدى المنتِج أو المستهلك قبل أن يعطّل الطرف الآخر.

اقرأ الدليل: ما هو اختبار API؟ وكيف تختبر REST API

كيفية استخدام منسّق Swagger JSON

  1. الصق Swagger 2.0 JSON.
  2. اختر JSON منسّقاً أو JSON مصغّراً أو YAML، وحدّد ما إذا كنت تريد ترتيب المسارات والتعريفات.
  3. انسخ المستند المنسّق وراجع جدولي نقاط النهاية والتعريفات.

مزايا منسّق Swagger JSON

  • تنسيق أنيق أو تصغير أو تحويل Swagger 2.0 JSON إلى YAML
  • كشف الإصدار مع تحذيرات واضحة عند إدخال OpenAPI 3.x أو JSON لا يتبع المواصفة
  • جرد نقاط النهاية (الطريقة والمسار وoperationId والملخص والوسوم ورموز الاستجابة) وجدول التعريفات
  • عنوان URL الأساسي مجمَّع من schemes وhost وbasePath
  • مشكلات التحقق البنيوي مدرجة إلى جانب الإخراج المنسّق

مثال على منسّق Swagger JSON

جرد مواصفة Petstore

الإدخال:

{"swagger":"2.0","info":{"title":"Petstore","version":"1.0.5"},"host":"petstore.swagger.io","basePath":"/v2","paths":{"/pet/{petId}":{"get":{"operationId":"getPetById",…}}}}

النتيجة:

Specification: Swagger 2.0 · Base URL: https://petstore.swagger.io/v2
Endpoints: GET /pet/{petId} getPetById — responses 200, 404
Definitions: Pet (object) — id, name, status

الأسئلة الشائعة حول منسّق Swagger JSON

ما الفرق بين Swagger 2.0 وOpenAPI؟

أُعيدت تسمية Swagger 2.0 إلى OpenAPI 2.0 عندما انتقلت المواصفة إلى مؤسسة Linux Foundation. وأعاد OpenAPI 3.x هيكلتها: أصبحت host/basePath/schemes هي servers، وdefinitions هي components.schemas، ومعاملات المتن هي requestBody. تستهدف هذه الأداة مستندات 2.0 لكنها تنسّق مستندات 3.x أيضاً.

ماذا يعرض جدول نقاط النهاية؟

كل عملية مع طريقتها ومسارها وoperationId وملخصها ووسومها ورموز الاستجابة الموثّقة — جرد سريع للمراجعات والتخطيط للاختبارات.

هل يمكنني التصغير بدلاً من التنسيق؟

نعم. اختر «JSON مصغّر» لإنتاج أصغر مستند صالح، وهو مفيد للتضمين في ملفات الإعداد أو بوابات API.

هل يحوّل Swagger 2.0 إلى OpenAPI 3؟

لا — فهو ينسّق ويرتّب ويحوّل بين JSON وYAML فقط. استخدم محوّلاً مثل swagger2openapi للترحيل البنيوي، ثم تحقق من النتيجة باستخدام مدقّق OpenAPI.

المراجع

  • OpenAPI SpecificationOpenAPI Initiativeالمعيار لوصف واجهات REST: المسارات والعمليات والمعاملات والمخططات والاستجابات وأنظمة الأمان.
  • JSON Schema SpecificationJSON Schemaالمفردات المستخدمة لوصف بنية مستندات JSON والتحقق منها (الأنواع والحقول المطلوبة والصيغ).
  • RFC 9110: HTTP SemanticsIETF · 2022معاني أساليب HTTP وحقول الترويسات ورموز الحالة والتفاوض على المحتوى، بغضّ النظر عن إصدار البروتوكول.