Apicurio-studio: विनिर्देश दस्तावेजों में घटक वस्तुओं के लिए समर्थन संदर्भ

उदाहरण

मुख्य उपयोग का मामला जो इसे हल करेगा, वह उपयोगकर्ताओं को अपनी डेटा प्रकार परिभाषाओं को केंद्रीकृत करने की क्षमता देना है, शायद एक फ़ाइल (या फाइलों का एक सेट) में। फिर इन डेटा प्रकारों को उनके केंद्रीय स्थान को संदर्भित करके कई एपीआई परिभाषाओं में लीवरेज किया जा सकता है।

विचार

बाहरी संदर्भों का समर्थन करने के लिए, कई संवर्द्धन की आवश्यकता है। यहाँ बिना किसी विशेष क्रम के एक सूची दी गई है:

• डेटा मॉडल लाइब्रेरी (वर्तमान में oai-ts-core लेकिन जल्द ही apicurio-data-models ) को प्लग करने योग्य संदर्भ रिज़ॉल्वर का समर्थन करने के लिए बढ़ाया जाना चाहिए। वर्तमान में ये पुस्तकालय केवल आंतरिक संदर्भों को हल करने में सक्षम हैं। इसके बजाय, पुस्तकालय के एक उपभोक्ता को एक कस्टम संदर्भ रिज़ॉल्वर प्रदान करने में सक्षम होना चाहिए ताकि बाहरी संदर्भों को सफलतापूर्वक हल किया जा सके।

• Apicurio Studio को "केवल डेटा प्रकार" शैली संसाधन का समर्थन करना चाहिए, एक संपादक के साथ जो डेटा प्रकारों को डिज़ाइन करने पर केंद्रित है। यह API डिज़ाइन से स्वतंत्र रूप से डेटा प्रकार बनाने/प्रबंधित करने के लिए अधिक विशिष्ट वर्कफ़्लो की अनुमति देता है।

• एपीआई डिज़ाइन संपादक में एक प्रकार सेट करते समय, टूलिंग को बाहरी संसाधनों से प्रकारों का चयन करने के तरीके की आवश्यकता होती है। हमें यह विचार करने की आवश्यकता है कि चयन के लिए उपयोगकर्ता को इन बाहरी प्रकारों को सर्वोत्तम तरीके से कैसे प्रदर्शित किया जाए। ऐसा हो सकता है कि हमें एपीआई डिज़ाइन के लिए अन्य संसाधनों/फ़ाइलों को "आयात" करने के लिए एक तरीका चाहिए ताकि यूआई उपयोगकर्ता के लिए विकल्पों को कम कर सके और उन्हें समझदारी से प्रदर्शित कर सके। ध्यान रखें कि संपादक को किसी प्रकार के चयन UI नियंत्रण में अपने उपलब्ध डेटा प्रकारों को प्रदर्शित करने के लिए किसी भी बाहरी संसाधन को लाने और पार्स करने की आवश्यकता होगी।

• हमें यह तय करने की आवश्यकता हो सकती है कि क्या एपीआई डिज़ाइन में बाहरी संदर्भों के स्रोत के रूप में इन-प्रोग्रेस डेटा प्रकार संसाधनों का उपयोग किया जा सकता है। दूसरे शब्दों में, क्या एपीआई डिज़ाइन में "स्नैपशॉट" डेटा प्रकारों को संदर्भित करना संभव होना चाहिए? या बाहरी संदर्भों के लिए स्रोत के रूप में उपयोग किए जाने से पहले हमें डेटा प्रकार संसाधन को "अंतिम" होने की आवश्यकता होनी चाहिए। यदि पूर्व, तो हम एक एपीआई डिज़ाइन को तब तक "अंतिम रूप" नहीं दे सकते जब तक कि उसकी निर्भरता को भी अंतिम रूप नहीं दिया जाता। नोट: इस पूरी अवधारणा के लिए हमें एपिक्यूरियो में अंतिम रूप देने वाले संसाधनों को लागू करने की आवश्यकता है!

• Apicurio संसाधनों का संदर्भ देते समय हमें यह तय करने की आवश्यकता होगी कि $ref प्रारूप क्या होगा। वर्तमान में किसी भी एपीआई डिज़ाइन (या सैद्धांतिक डेटा प्रकार संसाधन) की एक अद्वितीय आईडी है, लेकिन यह एक अपारदर्शी आईडी है जो निर्माण पर उत्पन्न होती है। वह आईडी वर्तमान में समाधान उद्देश्यों के लिए संसाधन की पहचान करने का एकमात्र अनूठा तरीका है। एक बार संसाधन को अंतिम रूप देने के बाद (यदि हम इस तरह की अवधारणा का समर्थन करते हैं) तो हम शायद संसाधन को अधिक मानव अनुकूल पहचानकर्ता प्रदान कर सकते हैं और फिर इसे $ref URI में उपयोग कर सकते हैं। हम जो कुछ भी करते हैं, यह ध्यान दिया जाना चाहिए कि एपीआई रजिस्ट्री (एक और भविष्य की सुविधा) के लिए संसाधन प्रकाशित करते समय एपीआई डिजाइन में किसी भी $ संदर्भ को एपीआई रजिस्ट्री द्वारा कुछ समझदार तरीके से हल करने की आवश्यकता होगी।

यहां $ref लिए अनुमत मानों के बारे में कुछ जानकारी दी गई है:

भले ही $ref का मान एक URI है, यह नेटवर्क लोकेटर नहीं है, केवल एक पहचानकर्ता है। इसका मतलब है कि स्कीमा को उस यूआरआई पर पहुंच योग्य होने की आवश्यकता नहीं है, लेकिन यह हो सकता है। यह मूल रूप से सत्यापनकर्ता कार्यान्वयन पर निर्भर करता है कि बाहरी स्कीमा यूआरआई को कैसे संभाला जाएगा, लेकिन किसी को यह नहीं मानना ​​​​चाहिए कि सत्यापनकर्ता $ ref मानों में इंगित नेटवर्क संसाधन प्राप्त करेगा।

संदर्भों के बारे में अधिक जानकारी OpenAPI विनिर्देश और JSON संदर्भ RFC में पाई जा सकती है।

क्या एपिकुरियो के भीतर किसी अन्य विनिर्देश से डेटाटाइप के संदर्भों के कार्यान्वयन को प्राथमिकता देना संभव होगा (प्रारंभ में बाहरी संदर्भों के बजाय)?

मेरे कहने का कारण यह है कि स्वैगर के किसी भी गैर-तुच्छ उपयोग के लिए कुछ क्रॉस-रेफरेंस कार्यक्षमता आवश्यक है। उदाहरण के लिए, हम विभिन्न सेवाओं को लागू कर रहे हैं जो डेटा प्रकार (जैसे पते, लोग इत्यादि) साझा करते हैं और इन सभी के विनिर्देशों के लिए एपिकुरियो का उपयोग करना चाहते हैं। हालाँकि, इस समय हम क्रॉस-रेफरेंस का उपयोग करने में असमर्थता के कारण ऐसा नहीं कर सकते।

क्या एपिकुरियो के भीतर किसी अन्य विनिर्देश से डेटाटाइप के संदर्भों के कार्यान्वयन को प्राथमिकता देना संभव होगा (प्रारंभ में बाहरी संदर्भों के बजाय)?

मेरे कहने का कारण यह है कि स्वैगर के किसी भी गैर-तुच्छ उपयोग के लिए कुछ क्रॉस-रेफरेंस कार्यक्षमता आवश्यक है। उदाहरण के लिए, हम विभिन्न सेवाओं को लागू कर रहे हैं जो डेटा प्रकार (जैसे पते, लोग इत्यादि) साझा करते हैं और इन सभी के विनिर्देशों के लिए एपिकुरियो का उपयोग करना चाहते हैं। हालाँकि, इस समय हम क्रॉस-रेफरेंस का उपयोग करने में असमर्थता के कारण ऐसा नहीं कर सकते।

सहमत, यह हमें हत्यारा ऐप क्षेत्र में लाएगा।

@jsenko ऐसा लगता है कि एक बार जब हम रजिस्ट्री मिलती है । :)

मुझे यह देखना अच्छा लगेगा, काम पर एपिक्यूरियो का उपयोग करना और संदर्भ विभिन्न टीमों के लिए अविश्वसनीय रूप से उपयोगी होंगे।

मुझे एहसास है कि इसमें थोड़ा समय लगा है, लेकिन बाहरी संदर्भों को आधिकारिक तौर पर बीटा 2.46 के रूप में समर्थित किया जाएगा, जो कि अगली रिलीज है (उम्मीद है कि कल किया जाएगा)। अन्य Apicurio Studio दस्तावेज़ों से डेटा प्रकारों और प्रतिक्रियाओं को वर्तमान में आयात करने के लिए एक नया UI है। इसके अलावा, बाहरी http/s के साथ-साथ एपिकुरियो-आंतरिक संदर्भों को हल करने में सहायता के लिए सत्यापन को अद्यतन किया गया है। दस्तावेज़ों में संदर्भों के लिए परिपक्व समर्थन की दिशा में यह एक अच्छा पहला कदम होना चाहिए।