OpenAPI
OpenAPI (مواصفات OpenAPI، OAS) معيار مفتوح لوصف واجهة HTTP API بصيغة مقروءة آلياً: ما المسارات والطرق التي تملكها الخدمة، وما المعاملات التي تقبلها، وماذا تعيد، وكيف يُمرَّر المفتاح. تُكتب الوثيقة بصيغة JSON أو YAML، ويستطيع الناس والبرامج فهم API منها دون الوصول إلى الشيفرة المصدرية.
من أين جاء المعيار
نشأ المعيار من مواصفات Swagger التي صدرت أول مرة عام 2011. وفي 2015 جرى التبرع بـ Swagger 2.0 لمبادرة OpenAPI، وهي مشروع مفتوح تابع لمؤسسة Linux، ومنذ 2016 تُطوَّر المواصفات باسم OpenAPI. صدر الإصدار 3.0 عام 2017 والإصدار 3.1 في فبراير 2021؛ وأحدث خط هو 3.2 (مواصفات 3.1).
ماذا تصف الوثيقة
servers— الرابط الأساسي لـ API؛paths— المسارات والطرق: لكل عمليةoperationIdخاص بها وsummaryقصير ومعاملات مع موضعها (in: query وpath وheader) واستجابات حسب رمز الحالة؛components.schemas— مخططات الكائنات (في 3.1 تعتمد على JSON Schema 2020-12)؛components.securitySchemes— المصادقة، مثلاً مفتاح في ترويسة:type: apiKeyوin: header.
مقتطف مختصر من مواصفات Genesis API، عملية معدلات التمويل ومخطط المفتاح:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/funding/rates": {
"get": {
"operationId": "getFundingRates",
"summary": "Funding rates",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query", "required": false,
"schema": { "type": "string" } }
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": { "type": "apiKey", "in": "header",
"name": "X-API-Key" }
}
}
}
الحقول التي تبدأ بـ x- امتدادات للمواصفات: يسرد x-genesis-plans الخطط التي تشمل العملية.
فيمَ تُستخدم المواصفات
من استخداماتها التي يذكرها المعيار توليد التوثيق، وتوليد العملاء والخوادم بلغات مختلفة، والاختبار. وبالنسبة لوكلاء الذكاء الاصطناعي فالمواصفات مجموعة أدوات جاهزة: عملية لها operationId ووصف ومخطط معاملات تقابل أداة لـ استدعاء الدوال أو خادم MCP.
OpenAPI في Genesis API
مواصفات Genesis API موجودة على genesisarbitrage.com/openapi.json: OpenAPI 3.1 و37 عملية والمفتاح في الترويسة X-API-Key (المصادقة). ويمكن العثور عليها تلقائياً أيضاً: ملف /.well-known/api-catalog على genesisarbitrage.com، المحدَّد في RFC 9727، يشير إليها عبر الرابط service-desc. وطريقة ربط المواصفات بوكيل مشروحة في Genesis API لوكلاء الذكاء الاصطناعي.
انظر أيضاً: REST API، JSON، نقطة نهاية API، بيانات سوق العملات الرقمية لوكلاء الذكاء الاصطناعي.
أسئلة وأجوبة
هل Swagger وOpenAPI شيء واحد؟
هما معيار واحد باسمين: تُطوَّر مواصفات Swagger باسم OpenAPI منذ 2016. صدر الإصدار 2.0 باسم Swagger 2.0، ومنذ 3.0 يُنشر باسم OpenAPI Specification.
هل أحتاج SDK إن وُجدت مواصفات؟
ليس مع Genesis API: كل طلب هو GET بترويسة واحدة، فيكفي أي عميل HTTP. أما توليد عميل من المواصفات فيفيد إن أردت دوال مُنمَّطة.