مكتبة مرجع OpenAPI

الهدف

هذا الدليل هو عقد الاكتشاف لحزم مرجعية مدعومة بـ OpenAPI لبوابة القرار. إنه يجيب، عن كل حزمة:

1. أين هو ملف OpenAPI القياسي؟
2. هل هو مؤلف يدويًا أم مستمد من مصدر أعلى؟
3. أي نظام اختبار يفرض السلوك؟
4. أين توجد وثائق واجهة برمجة التطبيقات للمستخدمين البشر؟

العقد القياسي

المصدر القابل للقراءة آليًا هو:

• references/openapi/reference_library.json

تم التحقق منه بواسطة المخطط:

• references/openapi/reference_library.schema.json

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

• system-tests/src/suites/openapi_reference_library.rs

كتالوج الحزم الحالي

Pack ID	Domain	Canonical OpenAPI	Mirrors	System Test	Upstream Docs
courtlistener-legal-citation-v1	التحقق من الاقتباسات القانونية	references/openapi/courtlistener-legal-citation-v1/openapi.json	system-tests/tests/fixtures/legal_citation/courtlistener_reference_openapi.json و examples/agentic/legal-citation-verification/courtlistener_reference_openapi.json	legal_citation_reference_projection_first_end_to_end في system-tests/src/suites/legal_citation.rs	نظرة عامة على REST، بحث الاقتباس، جذر API (v4)

بيانات التغطية والتنفيذ

كل إدخال حزمة الآن يعلن:

1. execution_modes: مجموعة مطلوبة من offline_fixture و/أو live_opt_in.
2. coverage: required deterministic counts:
   • العمليات
   • حالات_مزيفة
   • حالات_معروفة_جيدة
   • حالات_غامضة
   • حالات_غير_صحيحة
3. live_mode: required env + CI policy contract:
   • مفعل_بواسطة_البيئة
   • required_env
   • optional_env
   • ci_policy (manual_only أو disabled)

بالنسبة لـ CourtListener، required_env فارغ عمدًا لأن مصادقة وقت التشغيل تستخدم secret://courtlistener/api_token المسبق التوفير من مخزن الأسرار المشفر. يتم استخدام COURTLISTENER_API_TOKEN فقط بواسطة أدوات التقاط التهيئة اليدوية، وليس أثناء تنفيذ الدخان المباشر في وقت التشغيل. قم بتخزين قيمة الرمز الخام؛ حيث تطبق بيانات التعريف الخاصة بتشغيل الوقت المطلوبة بادئة Token على المصادقة الصادرة. عندما يكون مفتاح الخزنة غير متاح/رأسياً، قم بتعيين DECISION_GATE_SECRETS_PASSPHRASE قبل أوامر secrets init/put/list حتى يمكن فتح المخزن المشفر.

قاعدة تأليف الإسقاط (معيارية)

يتم تقييم بيانات التعريف الخاصة بالإسقاط على مخطط الاستجابة الموحد/المحلول. بيانات التعريف الخاصة بالإسقاط على مستوى المكونات المشار إليها عبر $ref هي من الدرجة الأولى وموضوعة في الاعتبار.

لا تقم بإدراج مخططات استجابة مكررة فقط لتلبية فحوصات المستورد. احتفظ بموقع عرض قياسي واحد (عادةً هو مخطط المكون المرجعي) وكرر ذلك بايتًا مقابل بايت عبر نسخ الحزمة القياسية/النظامية/المثال.

سياسة أصل المصدر

لكل حزمة، يجب أن يعلن كتالوج provenance بوضوح عن الأصل:

• hand_authored_fixture
• upstream_openapi_snapshot
• generated_from_upstream_docs

تستخدم CourtListener حاليًا hand_authored_fixture.

تغطية البوابة الصعبة

تفرض CI القياسية بوابات حتمية غير متصلة بالإنترنت:

1. كتالوج JSON صالح وفقًا للمخطط.
2. جميع المسارات المفهرسة موجودة.
3. Canonical and mirrored OpenAPI artifacts are byte-equal (including operation_fixture_corpus.json وملفات بيان الالتقاط المباشر).
4. كتالوج system_test_name موجود في Docs/generated/testing/proof_catalog.json.
5. كتالوج docs_paths موجود في Docs/verification/registry.toml.
6. عناوين URL العلوية هي https:// مطلقة وكاملة البيانات الوصفية.
7. بيانات التغطية والتنفيذ/وضع البث المباشر صالحة هيكليًا.

لا يتم تشغيل أي فحوصات للوصول إلى الشبكة الحية في CI القياسي.

قائمة التحقق للحزمة الجديدة (جاهز لـ PubMed/arXiv)

استخدم هذه القائمة عند إضافة DG + PubMed، DG + arXiv، أو ما شابه:

1. Create canonical directory: المراجع/openapi/<pack-id>/
2. Add canonical files:
   • openapi.json
   • typed_import_payload_example.json
   • citation_cases.json (أو مجموعة بيانات حتمية مكافئة للنطاق)
   • README.md
3. Add mirror copies under:
   • system-tests/tests/fixtures/<domain_pack>/
   • examples/agentic/<domain-pack>/
4. أضف/مدد مجموعة اختبارات النظام تحت system-tests/src/suites/.
5. تسجيل مجموعة الاختبارات في system-tests/tests/providers.rs.
6. تحديث crates/decision-gate-test-contracts/src/source_catalog.json و system-tests/TEST_MATRIX.md.
7. أضف إدخال الحزمة إلى references/openapi/reference_library.json.
8. تأكد من تسجيل docs_paths في Docs/verification/registry.toml.
9. تضمين روابط ماركداون المسماة إلى وثائق API في README الحزمة.
10. أعلن عن بيانات التعريف execution_modes و coverage و live_mode.

قالب البيانات الوصفية

{
  "pack_id": "<kebab-case-pack-id>",
  "version": "v1",
  "domain": "<domain>",
  "status": "active",
  "provenance": "hand_authored_fixture",
  "canonical_openapi_path": "references/openapi/<pack-id>/openapi.json",
  "system_fixture_openapi_path": "system-tests/tests/fixtures/<pack>/openapi.json",
  "example_openapi_path": "examples/agentic/<pack>/openapi.json",
  "system_suite_path": "system-tests/src/suites/<suite>.rs",
  "system_test_name": "<exact_test_name>",
  "docs_paths": [
    "/docs/decision-gate/guides/openapi-reference-library"
  ],
  "upstream_docs": [
    {
      "label": "<human label>",
      "url": "https://...",
      "kind": "rest_overview",
      "verified_on_utc": "2026-02-21"
    }
  ],
  "execution_modes": [
    "offline_fixture",
    "live_opt_in"
  ],
  "coverage": {
    "operations": 4,
    "fabricated_cases": 6,
    "known_good_cases": 3,
    "ambiguous_cases": 1,
    "invalid_cases": 1
  },
  "live_mode": {
    "enabled_by_env": "COURTLISTENER_LIVE",
    "required_env": [],
    "optional_env": [
      "COURTLISTENER_BASE_URL",
      "COURTLISTENER_LIVE_CASE_LIMIT"
    ],
    "ci_policy": "manual_only"
  },
  "notes": "<deterministic note>"
}

الوثائق ذات الصلة

• دليل OpenAPI المTyped
• دليل مرجع الاقتباس القانوني
• خريطة طريق الاقتباس القانوني