حفظ الطلبات وأمثلة البروتوكولات

يفصل Powerduck الطلب الذي تختبره عن عقد API الذي تنشره.

الإجراء	النتيجة
حفظ من شريط URL	يحفظ إعدادات تصحيح الأخطاء المحلية لهذا الطلب، دون تعديل مستند OpenAPI.
طلب سريع: حفظ في المواصفة	يضيف عملية إلى المستند والمجلد المحددين.
طلب من المواصفة: تحديث المواصفة	يعرض الطريقة والمسار المستهدفين ومعاينة التعريف قبل تحديث العقد.
حفظ المستند / Cmd+S أو Ctrl+S	يكتب مستند OpenAPI الحالي على القرص. في علامة تبويب الطلب السريع، يحفظ الاختصار ذلك الطلب السريع.

يتضمن الطلب المحلي الخادم المحدد وعنوان URL والطريقة وقيم المعلمات والجسم والبرامج النصية وإعدادات النقل. تبقى مسودات طلبات المواصفة في الذاكرة أثناء التحرير؛ ويحفظها زر الحفظ في شريط URL بصورة دائمة في تخزين عملية العرض بالتطبيق تحت powerduck.debug.v1:. تُفصل الإدخالات بحسب معرّف المستند والمسار والطريقة. مسح بيانات المتصفح أو التطبيق يحذف هذه الحالة المحلية؛ وتصدير ملف OAS لا يشملها. هذا التخزين ليس خزنة أسرار مشفّرة: استخدم مراجع البيئة بدل بيانات الاعتماد الصريحة في عناوين الطلبات أو ترويساتها أو أجسامها. تستخدم عناصر المصادقة مسارًا منفصلًا لحفظ بيانات الاعتماد.

x-powerduck-request ليس امتدادًا رسميًا للعقد. لا تنتجه عمليتا الإضافة إلى المواصفة أو تحديثها، ولا يجوز استخدامه لوصف طريقة أو معلمة أو جسم طلب أو استجابة. مجرد فتح مستند لا يعيد كتابة نسخه الموجودة في عمليات أخرى.

تحديث التعريف بصورة صريحة

يعرض تحديث المواصفة معاينة للطريقة والمسار المستهدفين ويحافظ على الاستجابات والمخططات الحالية. لا تُضمَّن تعريفات المعلمات إلا عند اختيارها، ولا تُنسخ قيم تصحيح الأخطاء. لا يُضاف جسم JSON كمثال إلا باختيار صريح. تُستبعد أسماء حقول بيانات الاعتماد الشائعة، لكن راجع النصوص الحرة والأمثلة قبل النشر. البرامج النصية وتجاوزات المصادقة ليست حقولًا في العقد.

لا يمكن استبدال عملية مستهدفة موجودة بتغيير الطريقة أو المسار. تُعدَّل مراجع العمليات المحلية لتشير إلى الهدف الجديد. تُخزَّن طريقة مخصصة مثل PURGE في paths./cache.additionalOperations.PURGE وتتطلب OpenAPI 3.2. توضّح المعاينة هذا الشرط، ويضبط تطبيق التحديث إصدار المستند إلى 3.2.0. تحقّق أيضًا من دعم الأدوات التي ستستهلك المستند لهذا الإصدار.

يظل تحرير مخططات البروتوكول متاحًا عبر تحرير الوثائق. يغيّر ذلك التعريف صراحةً؛ ولا تؤدي عملية إرسال طلب تصحيح أخطاء أو حفظه إلى إعادة كتابة المخططات خفيةً.

أمثلة رسمية قابلة للتنزيل

هذه تعريفات أمثلة تتم صيانتها، وليست خدمات API عامة من Powerduck. تشير جميع نقاط النهاية إلى خدمات محلية توفرها أنت. استيراد ملف لا يشغّل الخدمات ولا يتصل بها تلقائيًا ولا يمنح بيانات اعتماد.

• جميع البروتوكولات
• HTTP وطريقة PURGE المخصصة
• SSE
• WebSocket
• GraphQL
• gRPC وecho.proto
• MCP Streamable HTTP
• A2A 1.0 JSON-RPC

بالنسبة إلى gRPC، نزّل echo.proto بجانب ملف YAML، ثم اختر مساره المحلي الفعلي في العميل عند الحاجة. يجب أن ينفّذ الخادم powerduck.examples.Echo/Echo على المنفذ 50051. تحتاج الأمثلة الأخرى أيضًا إلى خادم مطابق؛ فهي ليست عروضًا للتحقق من خادم خلفي يعمل فعليًا.

مرجع امتدادات العقد

لكل عملية طريقة OAS عادية وoperationId وsummary وresponses. تستخدم روابط البروتوكولات غير HTTP عملية OAS كنقطة مرجعية للتوثيق؛ ولا يعني post في مثال gRPC تحويل gRPC إلى نقطة نهاية REST.

الامتداد	المعنى والحقول المستخدمة في الأمثلة
x-protocol	sse أو websocket أو graphql أو grpc أو mcp أو a2a. يمكن حذفه مع HTTP.
x-session	يعلن جلسة بروتوكول طويلة الأمد؛ تستخدمه الأمثلة مع WebSocket وMCP.
x-websocket	url وsubprotocols الاختياري وheaders وmessages. تحتوي كل رسالة موثقة على id وname وtype وbody وrequestSchema وresponseSchema. لا تضع بيانات اعتماد في الترويسات.
x-graphql	endpoint وquery وoperationName وvariablesSchema وvariables القابلة للنشر وresponseSchema.
x-grpc	address وservice وmethod وkind وreflection وprotoPaths وincludeDirs وmessages الموثقة. يدعم kind القيم unary/server_streaming/client_streaming/bidi_streaming. تعتمد مسارات proto المحلية على بيئة النشر.
x-mcp	transport وendpoint وmethod والحقول الخاصة بالطريقة: name وargumentsSchema وarguments القابلة للنشر وresponseSchema. تستخدم عمليات الموارد uri؛ لا تجمع حقول طرق غير مرتبطة.
x-a2a	version وbinding وendpoint وmethod وrequestSchema وresponseSchema الصريحة وexample القابل للنشر. تختلف حمولات 0.3 و1.0؛ راجع A2A.
x-response-stream	إعلان اختياري لنية استخدام البث في GraphQL، عندما يدعم الخادم والنقل الفعليان البث. لا يلزم لطلبات GraphQL العادية.

يستخدم SSE الحقل القياسي responses.200.content.text/event-stream.itemSchema لوصف حمولة كل حدث. ويستخدم HTTP المعلمات وrequestBody وresponses ومخططات الأمان القياسية. لا تبتكر كتلة إعدادات x-sse ولا تخزّن حالة تصحيح الأخطاء كامتداد للعقد.

تتضمن الأمثلة إعدادات كاملة قابلة للاستخدام للربط المختار، لا جميع الخيارات المتنافية. يتطلب MCP stdio ملفًا تنفيذيًا محليًا مضبوطًا بصورة منفصلة؛ ولا تشغّله هذه الأمثلة القابلة للتنزيل تلقائيًا عن قصد.

تكامل الحزم

تدير واجهة سطح المكتب حفظ حالة تصحيح الأخطاء المحلية والكتابة الصريحة للمواصفة. يقرأ @powerduck/openapi-parser الطرق المخصصة بالفعل عبر additionalOperations؛ ويستخدم @powerduck/tree و@powerduck/oas-document بنية العقد هذه. يتلقى @powerduck/openapi-request وسيطات التشغيل بصورة منفصلة عن المواصفة. تنفيذ الطلب لا يتطلب x-powerduck-request.

لا يضيف فصل الحفظ معلمات npm عامة جديدة. استخدم امتدادات البروتوكول الحالية لبيانات العقد، ومرّر قيم تصحيح الأخطاء الحالية إلى API تنفيذ الطلبات. لا تجعل أدوات التصدير أو التوليد أو MCP تعتمد على البنية الخاصة لحالة الطلب.