वेबस्केट घटनाओं या सॉगजर में कॉलबैक को दस्तावेज़ कैसे करें

Question

मेरे पास एक सेटअप है जहां मानक आरईएसटी का उपयोग करके कुछ संसाधन प्राप्त करना संभव है और यह आसानी से स्वैगर में प्रलेखित है। जब संसाधन बदल जाता है तो वेबसाइकिलों का उपयोग करके ग्राहकों को वही संसाधन धक्का दिया जाता है, इसलिए ग्राहकों को अंतराल के आधार पर खींच नहीं लेनी पड़ती है।

लेकिन मैं इसे स्वैगर में कैसे दस्तावेज कर सकता हूं? क्या यह भी संभव है? यदि नहीं, तो आरईएसटी एपीआई और वेबसाईट भाग दोनों को दस्तावेज करने के लिए आप किस अन्य टूल की सिफारिश करते हैं?

Answer 1

स्वैगर स्पेस संचालन के सीमित सेट को परिभाषित करता है, जिसे आप अपनी स्कीमा में किसी विशेष path object के लिए परिभाषित कर सकते हैं। ऐसा कहा जा रहा है कि, यदि आप केवल मानव उपयोग के लिए अपने एपीआई को दस्तावेज करने की परवाह करते हैं तो आप spec के बाहर कदम उठाने के लिए स्वतंत्र हैं। उदाहरण के लिए WIX docs पर एक नज़र डालें। यह अपने वेबहुक एपीआई को दस्तावेज करने के लिए एक कस्टम HOOK परिभाषा का उपयोग करता है और यह एक वैध स्वैगर स्पेक होने का नाटक करता है, जो आपके मामले में केवल वही हो सकता है जो आपको चाहिए।

Answer 2

आज "एसिंक संचार का उपयोग करके एपीआई दस्तावेज कैसे करें" पर स्पष्ट उत्तर ढूंढना मुश्किल है। यह न केवल WebSocket के बारे में, लेकिन यह भी Server Send events और दूसरों है ....

आज, बाकी विनिर्देश के लिए, यहां कई प्रसिद्ध विनिर्देशों रहे हैं और शीर्ष 3 है: - Swagger - RAML - API Blue Print

वे websocket का उपयोग कर एपीआई दस्तावेज करने के तरीके के बारे में बहुत सी समस्या/चर्चा है ...

लेकिन स्वैगर समुदाय की सहायता से एपीआई विनिर्देश मानकीकृत कर रहा है। इसका नाम OpenApi है।

ओपनएपीआई विनिर्देशों का संस्करण 3 document webhook/callback पर एक तरीका पेश करता है।

एक और अच्छा विनिर्देश asyncapi.com है जो गहराई से चल रहा है और readeable openApi चश्मे का सम्मान करता है।

Answer 3

स्वैगर 3 (या ओपनएपीआई) ने प्रतिक्रिया प्रारूपों में अपग्रेड किया है जहां उन्होंने कॉलबैक की अवधारणा को जोड़ा है, जो आपको वेबहुक परिभाषित करने की अनुमति देता है। प्रलेखन के इस भाग पर एक नज़र डालें: response format।

स्वैगर में 2 मैं क्या करने के लिए उपयोग API पद्धति है कि ठीक उसी मैं एक कॉलबैक से उम्मीद और मैं सिर्फ मूल विधि कि कॉलबैक इंतजार कर रहा है में इसे संदर्भ को लागू करता है को लागू करने की है। इसलिए कोई भी उपभोक्ता कम से कम संदेश के प्रारूप को देख सकता है जिसे मैं उनसे अपेक्षा कर रहा हूं, स्वैगर विनिर्देश का उपयोग कर।