अनुरोध सहेजना और प्रोटोकॉल उदाहरण

Powerduck आपके परीक्षण अनुरोध को प्रकाशित किए जाने वाले API अनुबंध से अलग रखता है।

कार्रवाई	परिणाम
URL बार में सहेजें	इस अनुरोध का स्थानीय डीबग कॉन्फ़िगरेशन सहेजता है। OpenAPI दस्तावेज़ नहीं बदलता।
त्वरित अनुरोध: विनिर्देश में सहेजें	चुने गए दस्तावेज़ और फ़ोल्डर में ऑपरेशन जोड़ता है।
विनिर्देश अनुरोध: विनिर्देश अपडेट करें	अनुबंध अपडेट करने से पहले लक्ष्य मेथड, पथ और परिभाषा का पूर्वावलोकन दिखाता है।
दस्तावेज़ सहेजें / Cmd+S या Ctrl+S	वर्तमान OpenAPI दस्तावेज़ डिस्क पर लिखता है। त्वरित अनुरोध टैब में यह शॉर्टकट उस त्वरित अनुरोध को सहेजता है।

स्थानीय अनुरोध में चुना सर्वर, URL, मेथड, पैरामीटर मान, बॉडी, स्क्रिप्ट और ट्रांसपोर्ट सेटिंग होती हैं। संपादन के दौरान विनिर्देश अनुरोध का ड्राफ़्ट मेमोरी में रहता है; URL बार में सहेजने से यह ऐप की रेंडरर प्रक्रिया के स्टोरेज में powerduck.debug.v1: के अंतर्गत स्थायी रूप से सहेजा जाता है। प्रविष्टियाँ दस्तावेज़ ID, पथ और मेथड के आधार पर अलग होती हैं। ब्राउज़र या डेस्कटॉप ऐप डेटा मिटाने पर यह स्थानीय स्थिति भी मिट जाती है; निर्यात की गई OAS फ़ाइल में यह शामिल नहीं होती। यह स्टोरेज एन्क्रिप्टेड सीक्रेट वॉल्ट नहीं है: अनुरोध URL, हेडर या बॉडी में सीधे क्रेडेंशियल लिखने के बजाय पर्यावरण संदर्भ इस्तेमाल करें। प्रमाणीकरण कंट्रोल क्रेडेंशियल सहेजने के लिए अलग व्यवस्था इस्तेमाल करते हैं।

x-powerduck-request आधिकारिक अनुबंध एक्सटेंशन नहीं है। विनिर्देश में जोड़ने या अपडेट करने पर यह नहीं बनता। इसे मेथड, पैरामीटर, अनुरोध बॉडी या प्रतिक्रिया बताने के लिए इस्तेमाल न करें। केवल दस्तावेज़ खोलने से अन्य ऑपरेशन में पहले से मौजूद इसकी प्रतियाँ दोबारा नहीं लिखी जातीं।

परिभाषा को स्पष्ट रूप से अपडेट करें

विनिर्देश अपडेट लक्ष्य मेथड और पथ का पूर्वावलोकन दिखाता है और मौजूदा प्रतिक्रियाएँ व स्कीमा सुरक्षित रखता है। पैरामीटर परिभाषाएँ केवल चुनने पर शामिल होती हैं; डीबग पैरामीटर मान कॉपी नहीं होते। JSON बॉडी भी स्पष्ट चयन के बाद ही उदाहरण बनती है। सामान्य क्रेडेंशियल फ़ील्ड नाम हटाए जाते हैं, फिर भी प्रकाशित करने से पहले मुक्त पाठ और उदाहरण जाँचें। स्क्रिप्ट और प्रमाणीकरण ओवरराइड अनुबंध फ़ील्ड नहीं हैं।

मेथड या पथ बदलकर मौजूदा लक्ष्य ऑपरेशन को ओवरराइट नहीं किया जा सकता। स्थानीय ऑपरेशन संदर्भ नए लक्ष्य पर अपडेट होते हैं। PURGE जैसा कस्टम मेथड paths./cache.additionalOperations.PURGE में सहेजा जाता है और उसे OpenAPI 3.2 चाहिए। पूर्वावलोकन यह आवश्यकता बताता है; अपडेट लागू करने पर दस्तावेज़ संस्करण 3.2.0 हो जाता है। दस्तावेज़ इस्तेमाल करने वाले अन्य टूल इस संस्करण का समर्थन करते हैं या नहीं, यह भी जाँचें।

प्रोटोकॉल स्कीमा को दस्तावेज़ संपादित करें से अभी भी बदला जा सकता है। यह परिभाषा में स्पष्ट बदलाव है; डीबग अनुरोध भेजने या सहेजने से प्रोटोकॉल स्कीमा चुपचाप नहीं बदलते।

डाउनलोड के लिए आधिकारिक उदाहरण

ये रखरखाव किए जा रहे उदाहरण विनिर्देश हैं, Powerduck की सार्वजनिक API सेवाएँ नहीं। सभी एंडपॉइंट आपके द्वारा उपलब्ध कराई जाने वाली स्थानीय सेवाओं की ओर इशारा करते हैं। फ़ाइल आयात करने से सेवाएँ शुरू नहीं होतीं, स्वतः कनेक्शन नहीं बनता और क्रेडेंशियल नहीं मिलते।

• सभी प्रोटोकॉल
• HTTP और कस्टम PURGE
• SSE
• WebSocket
• GraphQL
• gRPC और echo.proto
• MCP Streamable HTTP
• A2A 1.0 JSON-RPC

gRPC के लिए YAML फ़ाइल के साथ echo.proto डाउनलोड करें और ज़रूरत हो तो क्लाइंट में उसका वास्तविक स्थानीय पथ चुनें। सर्वर को पोर्ट 50051 पर powerduck.examples.Echo/Echo लागू करना होगा। अन्य उदाहरणों के लिए भी संगत सर्वर चाहिए; ये चल रहे बैकएंड पर सत्यापन के डेमो नहीं हैं।

अनुबंध एक्सटेंशन संदर्भ

हर ऑपरेशन में सामान्य OAS मेथड, operationId, summary और responses होते हैं। गैर-HTTP बाइंडिंग दस्तावेज़ के संदर्भ बिंदु के रूप में OAS ऑपरेशन इस्तेमाल करती हैं; gRPC उदाहरण में post का मतलब 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 के लिए अलग से कॉन्फ़िगर किया गया स्थानीय निष्पादन योग्य प्रोग्राम चाहिए; डाउनलोड उदाहरण जानबूझकर इसे स्वतः शुरू नहीं करते।

पैकेज एकीकरण

डेस्कटॉप UI स्थानीय डीबग स्थिति सहेजने और विनिर्देश में स्पष्ट लेखन का प्रबंधन करता है। @powerduck/openapi-parser पहले से additionalOperations के ज़रिए कस्टम मेथड पढ़ता है; @powerduck/tree और @powerduck/oas-document यही अनुबंध संरचना इस्तेमाल करते हैं। @powerduck/openapi-request रनटाइम आर्ग्युमेंट विनिर्देश से अलग लेता है। अनुरोध चलाने के लिए x-powerduck-request ज़रूरी नहीं है।

सहेजने की भूमिकाएँ अलग करने से नए सार्वजनिक npm पैरामीटर नहीं जुड़ते। अनुबंध डेटा के लिए मौजूदा प्रोटोकॉल एक्सटेंशन इस्तेमाल करें और वर्तमान डीबग मान अनुरोध निष्पादन API को दें। एक्सपोर्टर, जनरेटर या MCP टूल को निजी अनुरोध-स्थिति संरचना पर निर्भर न बनाएँ।