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

تحويل TypeScript إلى JSON Schema — Numio

يُنشئ JSON Schema بإصدار draft-07 من أنواع TypeScript باستخدام ts-json-schema-generator. يوضع كل نوع ضمن "definitions"؛ وتُستبعد الخصائص الاختيارية من "required"، وتحصل الكائنات على "additionalProperties": false.

أنواع الطلبات والاستجابات لديك واجهات TypeScript وتحتاج إلى JSON Schema للتحقق عبر Ajv أو لبوابة API.

TypeScript

JSON Schema

متى تستخدمها

  • أنواع الطلبات والاستجابات لديك واجهات TypeScript وتحتاج إلى JSON Schema للتحقق عبر Ajv أو لبوابة API.
  • تريد نشر مخطط لملف إعداد JSON معرَّف شكله مسبقًا كنوع TypeScript.

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

  1. الصق واجهات TypeScript أو أسماء أنواع مستعارة. تُقرأ وسوم JSDoc مثل @minimum أو @format أو @pattern إلى المخطط.
  2. تُرسَل الشيفرة المصدرية إلى /api/typescript-to-json-schema، وتُكتب في ملف مؤقت على الخادم، وتُعالَج مع كشف جميع الأنواع.
  3. انسخ JSON Schema. إذا لم تحتوِ المدخلات إلا على نوع واحد، يحصل الجذر أيضًا على $ref يشير إليه.

TypeScript

/** A product in the catalog */
export interface Product {
  /** @minimum 0 */
  price: number;
  name: string;
  tags?: string[];
}

JSON Schema (draft-07)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/Product",
  "definitions": {
    "Product": {
      "type": "object",
      "properties": {
        "price": {
          "type": "number",
          "minimum": 0
        },
        "name": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "price",
        "name"
…

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

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

يُحلَّل JSDoc في الوضع الموسَّع: يصبح تعليق الوصف "description"، وتصبح الوسوم مثل @minimum 0 أو @minLength 1 كلمات مفتاحية.

تُتخطّى التوابع في الواجهات. يصبح Date سلسلة string مع format date-time، وتصبح اتحادات القيم الحرفية enum.

bigint غير مدعوم ويعيد خطأ "Unknown node". يُوصف Map وSet بواجهتيهما، أي كائن لا يحتوي إلا على size رقمي، لذا استخدم Record<string, T> أو المصفوفات لبيانات JSON.

FAQ

هل تُضمَّن الأنواع غير المُصدَّرة؟

نعم. يُضاف كل نوع في المدخلات، مُصدَّرًا كان أم لا، إلى "definitions"، وتستخدم المراجع بينها $ref.

كيف تُمثَّل الخصائص الاختيارية والقابلة لـ null؟

تُستبعد الخصائص الاختيارية من "required". ويصبح الاتحاد مع null إلى anyOf مع {"type": "null"}.

لماذا يوجد $ref في الجذر؟

عند وجود نوع واحد يجعل المولِّد الجذر يشير إليه عبر $ref. وعند وجود عدة أنواع لا يُخرَج إلا "definitions".

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