انتقل إلى المحتوى
Numio

تحويل JSON Schema إلى مخطط OpenAPI — Numio

يحوّل JSON Schema (draft-04 وما بعده) إلى OpenAPI 3.0 Schema Object. تصبح مصفوفات type التي تحتوي على "null" إلى "nullable: true"، ويصبح const قيمة enum بعنصر واحد، ويصبح examples قيمة example واحدة.

تتحقق من الحمولات بمخطط draft-07 وتحتاج النموذج نفسه ضمن components/schemas في مستند OpenAPI 3.0.

JSON Schema

Open API Schema

متى تستخدمها

  • تتحقق من الحمولات بمخطط draft-07 وتحتاج النموذج نفسه ضمن components/schemas في مستند OpenAPI 3.0.
  • أدوات OpenAPI 3.0 لديك ترفض "type": ["string", "null"] وتحتاج إلى إعادة كتابة الحقول القابلة لـ null.

طريقة الاستخدام

  1. الصق JSON Schema في لوحة JSON Schema؛ يجب أن يكون JSON صالحًا لأن الصفحة تحلّله قبل الإرسال.
  2. يُرسَل المخطط إلى /api/json-schema-to-openapi-schema ويُحوَّل على الخادم؛ وتعرض اللوحة إشعارًا بذلك.
  3. انسخ النتيجة من لوحة Open API Schema وضعها ضمن components/schemas في ملف OpenAPI لديك.

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "kind": { "const": "invoice" },
    "total": { "type": ["number", "null"], "exclusiveMinimum": 0 },
    "notes": { "type": "string", "examples": ["Net 30"] }
  },
  "required": ["kind"]
}

OpenAPI 3.0 Schema Object

{
  "type": "object",
  "properties": {
    "kind": {
      "enum": [
        "invoice"
      ]
    },
    "total": {
      "type": "number",
      "exclusiveMinimum": true,
      "nullable": true,
      "minimum": 0
    },
    "notes": {
      "type": "string",
      "example": "Net 30"
    }
  },
  "required": [
    "kind"
  ]
}

التفاصيل والقيود

ترسل الصفحة مدخلاتك إلى مسار على الخادم (/api/json-schema-to-openapi-schema) لتحويلها؛ فهي لا تُعالَج في المتصفح فقط. تقبل مسارات API في Next.js افتراضيًا أجسام طلبات حتى 1 ميغابايت.

تُحذف الكلمة المفتاحية $schema. وتُعاد كتابة exclusiveMinimum/exclusiveMaximum الرقمية بصيغة OpenAPI 3.0: minimum/maximum مع علامة منطقية.

تبقى قيم $ref كما هي ولا تُنقل definitions إلى components/schemas، لذا عليك تصحيح مسارات المراجع بنفسك.

الهدف هو OpenAPI 3.0. يستخدم OpenAPI 3.1 مخطط JSON Schema مباشرةً ولا يحتاج عادةً إلى تحويل.

FAQ

كيف تُحوَّل الأنواع القابلة لـ null؟

مصفوفة type مثل ["number", "null"] تصبح "type": "number" مع "nullable": true، كما في المثال.

هل تُحَل مراجع $ref؟

لا. لا تقوم الصفحة بإلغاء المراجع؛ إذ يُنسخ "$ref": "#/definitions/Tag" وكتلة definitions دون تغيير.

ماذا يحدث لـ const وexamples؟

يصبح const قيمة enum بقيمة واحدة، وتُستبدل مصفوفة examples بقيمة example واحدة مأخوذة من عنصرها الأول.

المواصفات والمراجع