trustgraph/docs/tech-specs/openapi-spec.ar.md

layout	title	parent
default	مواصفات OpenAPI - المواصفات الفنية	Arabic (Beta)

مواصفات OpenAPI - المواصفات الفنية

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

الهدف

إنشاء مواصفات OpenAPI 3.1 شاملة وقابلة للتطوير لواجهة TrustGraph REST API التي: توثق جميع نقاط النهاية REST. تستخدم $ref خارجية من أجل modularity وقابلية الصيانة. تتوافق مباشرة مع كود مترجم الرسائل. توفر مخططات دقيقة للطلبات والاستجابات.

المصدر الموثوق

يتم تعريف واجهة برمجة التطبيقات بواسطة: مترجمو الرسائل: trustgraph-base/trustgraph/messaging/translators/*.py مدير الموزع: trustgraph-flow/trustgraph/gateway/dispatch/manager.py مدير نقطة النهاية: trustgraph-flow/trustgraph/gateway/endpoint/manager.py

هيكل الدليل

openapi/
├── openapi.yaml                          # Main entry point
├── paths/
│   ├── config.yaml                       # Global services
│   ├── flow.yaml
│   ├── librarian.yaml
│   ├── knowledge.yaml
│   ├── collection-management.yaml
│   ├── flow-services/                    # Flow-hosted services
│   │   ├── agent.yaml
│   │   ├── document-rag.yaml
│   │   ├── graph-rag.yaml
│   │   ├── text-completion.yaml
│   │   ├── prompt.yaml
│   │   ├── embeddings.yaml
│   │   ├── mcp-tool.yaml
│   │   ├── triples.yaml
│   │   ├── objects.yaml
│   │   ├── nlp-query.yaml
│   │   ├── structured-query.yaml
│   │   ├── structured-diag.yaml
│   │   ├── graph-embeddings.yaml
│   │   ├── document-embeddings.yaml
│   │   ├── text-load.yaml
│   │   └── document-load.yaml
│   ├── import-export/
│   │   ├── core-import.yaml
│   │   ├── core-export.yaml
│   │   └── flow-import-export.yaml      # WebSocket import/export
│   ├── websocket.yaml
│   └── metrics.yaml
├── components/
│   ├── schemas/
│   │   ├── config/
│   │   ├── flow/
│   │   ├── librarian/
│   │   ├── knowledge/
│   │   ├── collection/
│   │   ├── ai-services/
│   │   ├── common/
│   │   └── errors/
│   ├── parameters/
│   ├── responses/
│   └── examples/
└── security/
    └── bearerAuth.yaml

ربط الخدمات

الخدمات العامة (/api/v1/{kind})

config - إدارة التكوين flow - دورة حياة التدفق librarian - مكتبة المستندات knowledge - نوى المعرفة collection-management - بيانات وصفية للمجموعة

الخدمات المستضافة على التدفق (/api/v1/flow/{flow}/service/{kind})

الطلب/الاستجابة: agent, text-completion, prompt, mcp-tool graph-rag, document-rag embeddings, graph-embeddings, document-embeddings triples, objects, nlp-query, structured-query, structured-diag

إرسال واستقبال: text-load, document-load

الاستيراد/التصدير

/api/v1/import-core (POST) /api/v1/export-core (GET) /api/v1/flow/{flow}/import/{kind} (WebSocket) /api/v1/flow/{flow}/export/{kind} (WebSocket)

أخرى

/api/v1/socket (WebSocket متعدد) /api/metrics (Prometheus)

النهج

المرحلة الأولى: الإعداد

1. إنشاء هيكل الدليل
2. إنشاء ملف رئيسي openapi.yaml مع البيانات الوصفية والخوادم والأمان
3. إنشاء مكونات قابلة لإعادة الاستخدام (أخطاء، معلمات شائعة، مخططات أمان)

المرحلة الثانية: المخططات الشائعة

إنشاء مخططات مشتركة تستخدم عبر الخدمات: RdfValue, Triple - هياكل RDF/ثلاثية ErrorObject - استجابة الخطأ DocumentMetadata, ProcessingMetadata - هياكل البيانات الوصفية المعلمات الشائعة: FlowId, User, Collection

المرحلة الثالثة: الخدمات العامة

لكل خدمة عامة (تكوين، تدفق، أمين مكتبة، معرفة، إدارة المجموعة):

1. إنشاء ملف مسار في paths/
2. إنشاء مخطط الطلب في components/schemas/{service}/
3. إنشاء مخطط الاستجابة
4. إضافة أمثلة
5. الإشارة من الملف الرئيسي openapi.yaml

المرحلة الرابعة: الخدمات المستضافة على التدفق

لكل خدمة مستضافة على التدفق:

1. إنشاء ملف مسار في paths/flow-services/
2. إنشاء مخططات الطلب/الاستجابة في components/schemas/ai-services/
3. إضافة وثائق علامة التدفق حيثما ينطبق
4. الإشارة من الملف الرئيسي openapi.yaml

المرحلة الخامسة: الاستيراد/التصدير و WebSocket

1. توثيق نقاط النهاية الأساسية للاستيراد/التصدير
2. توثيق أنماط بروتوكول WebSocket
3. توثيق نقاط نهاية استيراد/تصدير WebSocket على مستوى التدفق

المرحلة السادسة: التحقق من الصحة

1. التحقق من الصحة باستخدام أدوات التحقق من صحة OpenAPI
2. الاختبار باستخدام واجهة Swagger UI
3. التحقق من تغطية جميع المترجمين

اصطلاح تسمية الحقول

جميع الحقول في JSON تستخدم kebab-case: flow-id, blueprint-name, doc-limit, entity-limit، إلخ.

إنشاء ملفات المخططات

لكل مترجم في trustgraph-base/trustgraph/messaging/translators/:

1. قراءة طريقة مترجم to_pulsar() - يحدد مخطط الطلب
2. قراءة طريقة مترجم from_pulsar() - يحدد مخطط الاستجابة
3. استخراج أسماء وأنواع الحقول
4. إنشاء مخطط OpenAPI مع: أسماء الحقول (kebab-case) الأنواع (سلسلة، عدد صحيح، منطقي، كائن، مصفوفة) الحقول المطلوبة القيم الافتراضية الأوصاف

مثال لعملية التعيين

# From retrieval.py DocumentRagRequestTranslator
def to_pulsar(self, data: Dict[str, Any]) -> DocumentRagQuery:
    return DocumentRagQuery(
        query=data["query"],                              # required string
        user=data.get("user", "trustgraph"),             # optional string, default "trustgraph"
        collection=data.get("collection", "default"),     # optional string, default "default"
        doc_limit=int(data.get("doc-limit", 20)),        # optional integer, default 20
        streaming=data.get("streaming", False)            # optional boolean, default false
    )

الترجمة:

# components/schemas/ai-services/DocumentRagRequest.yaml
type: object
required:
  - query
properties:
  query:
    type: string
    description: Search query
  user:
    type: string
    default: trustgraph
  collection:
    type: string
    default: default
  doc-limit:
    type: integer
    default: 20
    description: Maximum number of documents to retrieve
  streaming:
    type: boolean
    default: false
    description: Enable streaming responses

الاستجابات المتدفقة

الخدمات التي تدعم التدفق تُرجع استجابات متعددة مع العلامة end_of_stream: agent، text-completion، prompt document-rag، graph-rag

قم بتوثيق هذا النمط في مخطط استجابة كل خدمة.

استجابات الأخطاء

يمكن لجميع الخدمات إرجاع:

error:
  oneOf:
    - type: string
    - $ref: '#/components/schemas/ErrorObject'

حيث أن ErrorObject هو:

type: object
properties:
  type:
    type: string
  message:
    type: string

المراجع

المترجمون: trustgraph-base/trustgraph/messaging/translators/ تعيين الموزع: trustgraph-flow/trustgraph/gateway/dispatch/manager.py توجيه نقطة النهاية: trustgraph-flow/trustgraph/gateway/endpoint/manager.py ملخص الخدمة: API_SERVICES_SUMMARY.md