⛷️ 🤲🏿 ❄️ इसे निर्दिष्ट करें। यैंडेक्स रिपोर्ट 📗 🦍 🔞

एक अच्छा एपीआई विनिर्देश ग्राहकों को इसका उपयोग करने में मदद करता है। बिग पाइटअप में कुछ महीने पहले, यैंडेक्स डेवलपर अलेक्जेंडर ब्रायजिनbryazginnnREST API विनिर्देश ओपनएपीआई + स्वैगर के उदाहरण के आधार पर क्या है और इस तरह के बंडल की आवश्यकता क्यों है, पर एक प्रस्तुति दी। सिनॉप्सिस से, आप यह पता लगा सकते हैं कि हमने तैयार सेवा में विनिर्देश की स्वचालित पीढ़ी को कैसे खराब कर दिया है, जो लाइब्रेरी हमारे लिए उपयोगी थीं और ओपनएपीआई विनिर्देश के आसपास किस तरह की ट्यूनिंग है।

- सभी को नमस्कार, मेरा नाम अलेक्जेंडर है। मैं आपसे विनिर्देशों के बारे में बात करना चाहूंगा।

विशेष रूप से, मैं कई विषयों पर संपर्क करना चाहूंगा। सबसे पहले, REST API विनिर्देशों के उदाहरण का उपयोग करते हुए विनिर्देश क्या हैं। इसके अलावा - जैसा कि हमने अपनी सेवा में विनिर्देशन की पीढ़ी को तेज कर दिया है। और अंत में, मीठे पक्ष पर - क्या उपकरण, ट्यूनिंग, हमारी विनिर्देश पीढ़ी के परिणामों का उपयोग करने के लिए, ओपनपीआई और स्वैगर यूआई जैसे विनिर्देश का उदाहरण का उपयोग करते हुए।

अन्य एपीआई विनिर्देश

मेरी रिपोर्ट में क्या विनिर्देश हैं और मुझे इससे क्या मतलब है?

सबसे पहले, यह इंटरफ़ेस विवरण भाषा है, इंटरफेस का वर्णन करने के लिए एक भाषा, कुछ विवरण जो एक विशिष्ट प्रारूप से मेल खाती है। इसे स्वचालित रूप से पार्स किया जा सकता है, क्योंकि इसका एक सख्त प्रारूप और ऐसी बारीकियां हैं कि यह उस भाषा पर निर्भर नहीं करता है जिसमें इंटरफ़ेस लागू किया गया है। यानी मान लीजिए कि आपके पास एक पायथन वेब सर्वर है, इंटरफ़ेस विवरण भाषा के लिए यह कोई मायने नहीं रखता है।

विशिष्टताओं को निर्दिष्ट करने के लिए बहुत सारी भाषाएँ हैं। ये REST, RPC, GraphQL आदि के लिए विनिर्देशन हैं। आज हम REST विनिर्देशन पर ध्यान केन्द्रित करेंगे।

Openapi

आइए OpenAPI उदाहरण का उपयोग करके विनिर्देशों के बारे में बात करते हैं।

सबसे पहले, आइए समझते हैं कि OpenAPI क्या है। विनिर्देशों का वर्णन करने के लिए यह केवल एक ही भाषा है। अपने आप से, यह एक फ़ाइल है - YAML, JSON या XML के प्रारूप में, जो कोई भी इसे अधिक पसंद करता है - इंटरफ़ेस, हैंडल-एंडपॉइंट और योजनाओं के विवरण के साथ।

अकड़

जब हम OpenAPI के बारे में बात करते हैं, तो हम स्वैगर के बारे में नहीं कह सकते।

स्वैगर अनिवार्य रूप से एक ओपनएपीआई यूआई है जो आपको अपने विनिर्देश को खूबसूरती से देखने की अनुमति देता है।

स्वैगर में, ओपनएपीआई में, एंडपॉइंट का वर्णन है जो आपके विनिर्देश में हैं।

आपके एपीआई में प्राधिकरण का वर्णन है।

उन मॉडलों या सर्किटों का वर्णन है जिनके साथ आप अपने एपीआई में हेरफेर करते हैं - उदाहरण के लिए, इसे इनपुट के लिए स्वीकार करें या आउटपुट के लिए इसे वापस करें।

आपके एपीआई से उदाहरणों और अपेक्षित अनुरोधों और प्रतिक्रियाओं का विवरण है।

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

^{_{स्लाइड से लिंक करें}}

इस सब के साथ, आप स्वैगर टीम द्वारा तैयार किए गए टेस्ट बेंच पर खेल सकते हैं। यह petstore.swagger.io है। एक उदाहरण विनिर्देश है, जिसे स्वैगर द्वारा उठाया गया है। आप वास्तविक बैकएंड पर जा सकते हैं और स्पर्श कर सकते हैं। सलाह देते हैं।

तो, हम कहते हैं: ओपनएपीआई, स्वैगर, विनिर्देश। लेकिन यह सब एक ऐसे व्यक्ति के लिए क्यों आवश्यक है जो एक बैकेंड लिखता है, कहता है?

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

इसके अलावा, एक लोकप्रिय मामला है। सेवा में हमारे लिए विनिर्देशन को किस ओर खींचा? यह दस्तावेज है। विनिर्देशों की उपलब्धता से आपको अपने एपीआई का वर्णन करने और किसी के साथ इस जानकारी को साझा करने का इतना अच्छा अवसर मिलता है: या तो आपकी टीम में फ्रंट-एंड प्रदाताओं के साथ, या बाहरी ग्राहकों के साथ जो आपके साथ एकीकरण करना चाहते हैं।

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

हम OpenAPI कैसे तैयार करते हैं

हमने फैसला किया कि हमें यह सब क्यों चाहिए। आइए इस बारे में बात करें कि हमने अपनी सेवा में विशिष्टताओं को कैसे बढ़ाया। पहला, थोड़ा संदर्भ।

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

और हमारा बैकएंड अचानक पायथन में था। हमने फाल्कन को एक फ्रेमवर्क के रूप में प्रयोग किया, मार्शमैलो को एक सीरीज़ेशन और डीरिएरलाइज़ेशन टूल के रूप में, और वेबरेज को एक सत्यापन उपकरण के रूप में इस्तेमाल किया।

पहले बताए गए पेटस्टोर से सबसे सरल क्लिपिंग का उपयोग करते हुए, हम कल्पना करते हैं कि जब हम विनिर्देश तैयार करना चाहते थे तो हमारी सेवा मंच पर कैसे दिख सकती है।

हमारी सेवा में, योजनाओं की एक सरलीकृत जोड़ी होगी: हमारे पालतू जानवर का प्रकार, वह है, श्रेणी, और, वास्तव में, जानवर स्वयं।

यही है, हम मार्शमैलो पर कई योजनाओं का वर्णन करेंगे। इसके अलावा, हम क्रम में कुछ पेन तैयार करेंगे, उदाहरण के लिए, अपने पसंदीदा को पंजीकृत करने और प्राप्त करने के लिए।

और, वास्तव में, वे स्वयं उस एप्लिकेशन का वर्णन करेंगे, जो पालतू जानवर बनाने और प्राप्त करने के लिए समापन बिंदु को बढ़ाएगा।

इस तरह से यह एक साथ दिखेगा। काफी सरल सेवा।

आइए इस बारे में सोचें कि OpenAPI कॉन्फिगरेशन बनाने के लिए हमारे पास क्या विकल्प हैं। सबसे सरल और सबसे भोला विकल्प, जैसा कि मैंने पहले कहा था, सिर्फ एक फाइल है। हम इस फ़ाइल को अपने हाथों से क्यों नहीं बनाते हैं? हमें पता है कि हमारे पास कौन सा इनपुट डेटा है, हमारे पास समापन बिंदु हैं। यह स्पष्ट लगता है, बस ले लो और लिखो।

लेकिन सबसे पहले, हम प्रोग्रामर हैं। हमें अपने हाथों से कुछ भी करना पसंद नहीं है। हम चाहते हैं कि कुछ मानक हमारे लिए उत्पन्न हों। दूसरे, अगर हम हाथ से सब कुछ का समर्थन करते हैं, तो हमें निश्चित रूप से एपीआई परिवर्तनों का समर्थन करना होगा, साथ ही एक फाइल जो कहीं और निहित है। किसी भी सेवा की तरह, हमारा उत्पाद अस्थिर है, और इसलिए विनिर्देश है।

इसलिए, हम इस निष्कर्ष पर पहुंचे हैं कि हम एक ओपनएपीआई कॉन्फ़िगरेशन उत्पन्न करना चाहते हैं। हमारी प्रौद्योगिकी के ढेर को देखते हुए, हमें एक पुस्तकालय जैसा मिला है, जिसमें से एक है । Apispec निर्माताओं से एक पुस्तकालय है, जो मार्शमैलो और वेबरग के लेखक हैं। साथ में वे एक बड़े पारिस्थितिकी तंत्र का निर्माण करते हैं।

आइए देखें कि आप हमारे स्टैक पर एपिसेप का उपयोग कैसे कर सकते हैं यह सिखाने के लिए कि हमारे लिए विनिर्देश कैसे उत्पन्न करें।

हमारे पास इस संसाधन की विधि के लिए एक संसाधन और एक विशिष्ट हैंडलर था। उसे किसी तरह का शरीर मिला है।

एपिसिपेक सिखाने के लिए, उसे यह बताने के लिए कि हम अपनी कलम में क्या कर रहे हैं, हम डॉकस्ट्रिंग में कुछ जोड़ते हैं। हम वहाँ एक विवरण जोड़ते हैं जो मनुष्य के लिए समझ में आता है। हमारे मामले में, यह उत्तर का एक उदाहरण है: कभी-कभी ऐसा होता है, हमारी कलम दो सौ के साथ जवाब देती है, और हमारे जवाब के शरीर में एक स्कीमा, पेट डेटा मॉडल के साथ JSON है।

पोस्ट-रिक्वेस्ट के उदाहरण का उपयोग करते हुए, हम वर्णन करते हैं: इस तथ्य के अलावा कि एक प्रतिक्रिया 201 है जिसमें हम पेट वापस करते हैं, हमारे पास आने वाले अनुरोध का अपेक्षित निकाय भी है। और इस अनुरोध के अंदर, हम JSON से अपेक्षा करते हैं, और उम्मीद करते हैं कि यह JSON पालतू प्रारूप में होगा।

हमने डॉकस्ट्रिंग्स को जोड़ा, फिर हमें यह जानने की आवश्यकता है कि विनिर्देश कैसे उत्पन्न किया जाए। ऐसा करने के लिए, हम किसी प्रकार की स्क्रिप्ट, एक लाल बटन लिखते हैं, और हमारे लिए एक विनिर्देशन उत्पन्न करने के लिए एपिस्पेक सिखाते हैं। हम एक अपरिहार्य वस्तु की घोषणा करते हैं, जिसमें से हम अपनी सेवा के कुछ मेटाडेटा का वर्णन करते हैं, और फिर हम बस फ़ाइल लिखते हैं, YAML प्रारूप में उत्पन्न विनिर्देश।

आइए देखें कि इस फ़ाइल में इस विशाल एप्लिकेशन के लिए क्या उत्पन्न हुआ था।

सबसे पहले, इस फ़ाइल में उस संस्करण का विवरण होगा जिसमें विनिर्देश उत्पन्न किया गया था। यह महत्वपूर्ण है ताकि हर कोई जो इस विनिर्देश की व्याख्या करता है वह समझता है कि किस प्रारूप की व्याख्या करनी है। निर्दिष्टीकरण संस्करण से संस्करण में भिन्न होते हैं।

आगे हमारी सेवा का विवरण है। यह शीर्षक, संस्करण, शायद कुछ विवरण होगा, यदि आप इसे चाहते हैं, और फिर सर्वर की एक सूची जिसे आप जा सकते हैं, कलम खींच सकते हैं, देख सकते हैं और हमारे बैकेंड को छू सकते हैं।

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

योजनाओं के अलावा, समापन बिंदुओं का वर्णन खुद वहां बढ़ता है। इस मामले में, प्रत्येक विधि का विवरण अंकुरित होता है।

प्राप्त विधि का उपयोग करके, हम प्राप्त विधि के साथ क्या करते हैं, इसका विवरण मिलता है।

और ठीक उसी तरह का वर्णन जो हम पोस्ट पर अंकुरित संगत समापन बिंदु के docstrings में डालते हैं। यानी हमें पहले ही किसी तरह की फाइल मिल गई है।

अब हम इसके साथ क्या करेंगे? उपयोग क्या है? सबसे पहले, आप, बैकएंड के मालिकों के रूप में, पहले से ही यह सभी संभावित ग्राहक दे सकते हैं जो आपके पेन में जाएंगे, यह विनिर्देश दें। और यह लोगों को एकीकृत करने में मदद करेगा। यही है, जो फ़ाइल हमने बनाई है वह आपको अपनी आँखों से बाहर नहीं निकालती है। यह काफी पठनीय है। यह आंखों के माध्यम से देखा जा सकता है और किसी भी तरह से पार्स किया जा सकता है।

लेकिन यह भी मुश्किल है। आइए देखें कि आपके जीवन को आसान बनाने के लिए अन्य कौन से उपकरण हैं और उत्पन्न विनिर्देश के आसपास किस तरह की ट्यूनिंग है।

बन्स

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

^{_{स्लाइड से लिंक}}

पहला उपकरण जिसके बारे में मैं बात करना चाहूंगा वह है स्वैगर-यूआई। इसके बाद, मैं या तो एक वेब संसाधन के लिए लिंक प्रदान करूँगा, जहाँ आप संबंधित टूल को प्रचलित कर सकते हैं, इस मामले में SwaggerHub, या Docker का उपयोग करके संबंधित दस्तावेज़ लॉन्च करने के लिए कमांड में।

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

तो, स्वैगर-यूआई वास्तव में, एक उपयोगिता है जो आपको अपने विनिर्देश को खूबसूरती से प्रदर्शित करने की अनुमति देती है। जैसा कि मैंने पहले कहा था, ये डॉकर, संभवतः स्वैगर का उपयोग करके स्थानीय रूप से चल रहे हैं।

आप अपने हार्डवेयर पर स्‍वैगर में स्‍पेसिफिकेशन चलाकर लोकल पर देख या शेयर कर सकते हैं। और अपने सभी संभावित उपयोगकर्ताओं को इस विनिर्देश में भेजें। वह पहले से ही बहुत अधिक समझदार, सुंदर है। सीधे तौर पर, आप क्वेरी निष्पादन कर सकते हैं।

^{_{स्लाइड से लिंक}}

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

अगला अप अद्भुत प्रिज्म टूल है। मैं इस पर अधिक विस्तार से ध्यान देना चाहूंगा। प्रिज्म स्पॉटलाइट से एक उपयोगिता है। यह आपको विनिर्देशन के साथ, मॉक-सर्वर को बढ़ाने की अनुमति देता है, जो उस विनिर्देश के अनुसार काम करेगा जिसे आपने उसे खिलाया था।

यही है, इस मामले में, हम विनिर्देशन के शीर्ष पर प्रिज्म के प्रक्षेपण को देखते हैं, जिसे मैंने स्वैगर स्टोर के नीचे से चुराया था। हम देखते हैं कि प्रिज़्म ने उन सभी एंडपॉइंट्स को पाया जो विनिर्देश में निर्दिष्ट हैं, और कहा कि वे ईमानदारी से उन्हें परेशान करते हैं।

आइए महसूस करने की कोशिश करें कि प्रिज्म क्या कर सकता है।

सबसे पहले, हम पेन पाते हैं, इसे खींचने की कोशिश करते हैं और अचानक हम देखते हैं कि प्रिज्म हमें बताता है: क्षमा करें, 401 त्रुटि। हम विनिर्देश में जाते हैं और देखते हैं कि वास्तव में यह पेन प्राधिकरण के पीछे छिपा हुआ है। सुरक्षा अनुभाग स्पष्ट रूप से वहां वर्णित है। इसमें, हम देखते हैं कि प्राधिकरण विधि OAuth है, और हम समझते हैं: वास्तव में, प्रिज्म ने हमसे किसी प्रकार के प्राधिकरण डेटा की अपेक्षा की थी।

आइए उस प्रारूप के अनुसार प्राधिकरण डेटा स्थानांतरित करने का प्रयास करें जिसका वह इंतजार कर रहा है। यह स्पष्ट है कि टोकन किसी तरह से हवादार है, प्रिज्म के लिए इससे कोई फर्क नहीं पड़ता कि यह क्या है। उसके लिए प्रारूप महत्वपूर्ण है। यही है, अगर वह OAuth की प्रतीक्षा कर रहा है, तो वह एक विशिष्ट प्रारूप में प्राधिकरण डेटा की प्रतीक्षा कर रहा है।

हम प्राधिकरण के साथ झटका करते हैं और पहले से ही 400 वीं त्रुटि देखते हैं। हम देखते हैं कि हमारे पास विनिर्देश में क्या है। विनिर्देशन में, हम देखते हैं कि हमने कुछ आवश्यक विशेषताओं को पारित नहीं किया है। चलिए उन्हें पास करते हैं।

जादू की विशेषता स्थिति है। यह वास्तव में, ENUM विनिर्देशन के अनुसार दिया गया है। यदि हमने एक स्थिति हस्तांतरित की है जो इस ENUM में शामिल नहीं है, तो हमें एक चार डॉट मिलेगा।

यहां हमने वैध स्थिति को पारित कर दिया और हम देखते हैं कि बैकएंड ने डेटा के साथ पूरी तरह से वैध xml के साथ प्रतिक्रिया दी। इस xml का डेटा अब केवल विनिर्देश में निर्दिष्ट उदाहरण से वापस आ गया है। यही है, प्रत्येक क्षेत्र के लिए विनिर्देश में उदाहरण के रूप में एक ऐसा खंड है, जहां आप डेटा का एक उदाहरण निर्दिष्ट कर सकते हैं जिसे वापस किया जा सकता है। यहां प्रिज्म उन्हें वापस ले आया।

लेकिन इस तथ्य के अलावा कि आप कलम को खींच सकते हैं और उम्मीद कर सकते हैं कि एक ईमानदार दो-सौ होगा, प्रिज्म कहने का एक अवसर है - मुझे एक विशिष्ट प्रतिक्रिया कोड लौटाएं। आमतौर पर विनिर्देश में हम अपनी कलम के विभिन्न व्यवहार का वर्णन करते हैं, और मान्य डेटा के साथ वे हमेशा दो सौ के अनुरूप नहीं होते हैं। वे देख सकते हैं, उदाहरण के लिए, डेटाबेस में आईडी की उपस्थिति के लिए, यह देखने के लिए कि ऐसी आईडी मौजूद नहीं है।

इस मामले के लिए, हम किसी निश्चित कोड की घोषणा करते हैं, कहते हैं, 400 वां या 422 वां, जैसा भी आप चाहें। यही है, एक वैध प्रविष्टि के साथ, हमेशा एक वैध निकास नहीं होता है। इसलिए, विनिर्देश में, हम विभिन्न उत्तर विकल्पों का वर्णन करते हैं। और हम स्पष्ट रूप से कह सकते हैं जब कलम को धक्का देते हैं प्रिज्म: इस बार मैं आपको जवाब देने के लिए इंतजार कर रहा हूं, कहो, 404 वीं त्रुटि। मान लीजिए कि यह एक ऐसा मामला है जब मैं एक आईडी के साथ हैंडल खींचता हूं, लेकिन ऐसी कोई आईडी नहीं है।

संक्षेप में, उन विशेषताओं के अलावा जो मैंने पहले ही उल्लेख किया है, सामान्य रूप से क्या हैं? फिर से, यह एक नकली सर्वर है जिसे आप उठा सकते हैं। वह विनिर्देश के अनुसार प्रतिक्रिया देगा, प्राधिकरण अनुरोधों को मान्य करेगा। यह आपके द्वारा भेजे गए डेटा पर भी मान्य होगा।

अनुरोध को मान्य करने के अलावा, यह प्रतिक्रियाएं उत्पन्न करेगा। सबसे सरल मामले में, जैसा कि मैंने कहा, यह उदाहरण से उत्तर उत्पन्न करता है। एक दूसरा विकल्प है - जब आप इसे स्पष्ट रूप से पूछते हैं: कृपया गतिशील उत्तर उत्पन्न करें। एक गतिशील रणनीति का मतलब है कि, प्रकार के आधार पर, कहते हैं, इंट, यह हजारों, अरबों, या कुछ और उत्पन्न करेगा। या स्ट्रिंग के लिए, एक अजीब और समझ से बाहर हैश।

इसके अलावा, जब मैंने पहले रन पर कहा कि आप डेटा जनरेट कर सकते हैं, तो हमने खुद से पूछा: यह अच्छा होगा अगर प्रिज्म फेक के साथ एकीकृत हो। जो लोग पायथन फेकर का उपयोग करते हैं, वे शायद जानते हैं कि जब आप कुछ डेटा लॉक करना चाहते हैं या डेटाबेस में डेटा का अनुकरण करना चाहते हैं तो यह कितना अच्छा है।

तो, प्रिज्म को जावास्क्रिप्ट में लिखा जाता है। जावास्क्रिप्ट में भी Faker.js है, और प्रिज़्म में faker के साथ स्वचालित एकीकरण है। आप स्पष्ट रूप से अपने विनिर्देश में निर्दिष्ट कर सकते हैं कि आपके पेन द्वारा दिए जाने वाले फेक डेटा के प्रकार। यही है, ओपनएपीआई एक प्लग-इन सिस्टम का समर्थन करता है जो आपको अपने विनिर्देश का विस्तार करने की अनुमति देता है ताकि ओपनएपीआई और पार्सर खुद परवाह न करें। लेकिन अगर आपके विनिर्देशन को पार्स करने वाले प्लगइन्स हैं, तो वे कुछ अतिरिक्त फ़ील्ड्स का उपयोग कर सकते हैं।

तो, प्रिज्म आपको वैकल्पिक X-faker प्लगइन क्षेत्र का उपयोग करने की पेशकश करता है। बहुत आराम से।

यहां, तारांकन के तहत, मैंने संकेत दिया कि कॉलबैक को ओपनएपीआई में वर्णित किया जा सकता है। यह इंटरैक्शन स्कीम है जब आप एक निश्चित पेन में कॉलबैक रजिस्टर करते हैं और इसके लिए प्रतीक्षा करते हैं, उसके बाद आपको आपके द्वारा पंजीकृत यूआरएल पर एक विशिष्ट कॉलबैक प्राप्त होगा। तो, प्रिज्म और यह पता है कि कैसे गीला होना है।

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

यदि कुछ डेटा - कहते हैं, इनपुट या आउटपुट, अनुरोध या प्रतिक्रिया - विचलन करेगा, तो वह लॉग में लिखेगा। वह इसे काफी पारदर्शी तरीके से करता है, यह वास्तविक व्यवहार को प्रभावित नहीं करता है। सामान्य तौर पर, प्रलेखन कहता है कि इसे उत्पादन में आसानी से उठाया जा सकता है। ईमानदारी से कहूं तो मैंने खुद इसे आजमाया नहीं है। निश्चित रूप से कुछ प्रकार का ओवरहेड है, लेकिन मैं अभी भी इसके बारे में नहीं कह सकता। आप महसूस कर सकते हैं, कोशिश कर सकते हैं और बता सकते हैं।

इसके अलावा, मैंने जो पहले ही कहा है, उसके माध्यम से कुछ अनुरोधों को लागू करना संभव है। यही है, मॉक सर्वर पर आओ और कहो: मैं एक विशिष्ट उदाहरण या प्रकार की प्रतिक्रिया चाहता हूं। हमने पहले से ही उत्तर के प्रकार के बारे में बात की थी। OpenAPI विनिर्देश में भी कई उत्तर विकल्पों को निर्दिष्ट करना और उन्हें स्पष्ट रूप से नाम देना संभव है।

तो, आप आकर प्रिज्म कह सकते हैं: इस बार मैं एक विशिष्ट उदाहरण चाहता हूं, अगली बार मुझे एक और उदाहरण चाहिए।

^{_{स्लाइड से लिंक}}

प्रिज्म के बारे में बात की। अब पोस्टमैन के बारे में। मैं उसे बहुत प्यार करता हूँ। तो, डाकिया ओपनएपीआई के साथ बॉक्स एकीकरण से बाहर है। आप बटन के सिर्फ दो क्लिक के साथ OpenAPI विनिर्देश को सचमुच आयात कर सकते हैं। और वह आपके विनिर्देशन के अनुसार अनुरोधों का एक संग्रह तैयार करेगा।

उसी समय, वह सभी क्वेरी पैरामीटर, सभी बॉडी पैरामीटर, सभी पर्यावरण और प्राधिकरण को पूर्व-तैयार करेगा। आपको बस कुछ वास्तविक आईडी या कुछ और के साथ डेटा खत्म करना होगा, प्राधिकरण टोकन। बहुत आराम से।

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

Dredd विनिर्देश को पार्स करता है। वह लेता है, सभी पेन खींचता है और देखता है कि उसके पास क्या लौट आया है। सामान्य तौर पर, ड्र्रेड को परीक्षण लिखने के लिए बुनियादी ढांचे के रूप में माना जा सकता है, क्योंकि इसके सभी अनुरोधों को इसके हुक के साथ पूरक किया जा सकता है। अर्थात्, बॉक्स से, जैसा कि मैंने इसे यहां लॉन्च किया है, वैसे ही आप ड्रेजड शुरू कर सकते हैं।

या आप इसे हुक का एक सेट पास करके ड्र्रेड चला सकते हैं जो वास्तव में एक नियमित परीक्षण की विचारधारा में काम करते हैं। ऐसा कुछ है जो परीक्षणों के पूरे सेट पर उगता है, ऐसे हुक हैं जो परीक्षण से पहले चलते हैं, परीक्षण के बाद, पूरे बुनियादी ढांचे के।

^{_{स्लाइड से लिंक}}

अगला मैं स्वैगर से ऐसे उपकरण के बारे में और अधिक विस्तार से बात करना चाहता हूं, जैसे स्वैगर-कोडजेन। वास्तव में, यह स्विस चाकू जैसा है। शुरू करने के लिए, लोगों ने किस तरह के विचारों को लिखा जब उन्होंने इस उपकरण को लिखा।

आमतौर पर, जब किसी को बैकएंड के साथ एकीकृत करने की आवश्यकता होती है, तो आप शायद ही कभी यहां एक http अनुरोध का वर्णन करते हैं, एक निश्चित चरण में, व्यापारिक तर्क में। ज्यादातर आप क्लाइंट में, किसी न किसी इकाई में एक विशिष्ट बैकएंड के साथ काम को संक्षिप्त कर देते हैं।

इसलिए, लोग इस विचार के साथ आए कि, एक विनिर्देशन होने के कारण, हम स्पष्ट रूप से वर्णन कर सकते हैं और भविष्यवाणी कर सकते हैं कि ग्राहक इस बैकएंड के लिए कैसा दिखेगा। और दोस्तों ने एक ग्राहक जनरेटर बनाया।

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

इसलिए, पायथन में क्लाइंट के अलावा, उसने डॉक्स और मैजिक फ़ोल्डरों के एक जोड़े को उत्पन्न किया। हम बाद में उनके बारे में अधिक विस्तार से बात करेंगे। और बहुत सारी चीनी ताकि आप इस ग्राहक को तैयार पुस्तकालय में लपेट सकें। Gitignore है, CI फाइलें हैं, चलो ट्रैविस के लिए कहते हैं, git के लिए चीनी है। आवश्यकताएँ, setup.py और tox.ini हैं। यही है, सब कुछ जो आपको बस ग्राहक को लेने, प्रतिबद्ध करने और भेजने में मदद करता है, पहले से ही एक पुस्तकालय के रूप में है जिसका पुन: उपयोग किया जा सकता है।

आइए ग्राहक में उसने जो कुछ भी उत्पन्न किया है, उस पर करीब से नज़र डालें।

क्लाइंट में, उन्होंने कुछ सहायक फाइलों के अलावा, दो बहुत ही महत्वपूर्ण निर्देशिका एपीआई और मॉडल तैयार किए। मॉडलों में, हमारे पास वे डेटा मॉडल होते हैं जिन्हें हम हेरफेर करते हैं। प्रत्येक मॉडल केवल एक पायथन वर्ग है, जिसे __init__ के साथ ऑब्जेक्ट से विरासत में मिला है, जो इस योजना के लिए सभी प्रकार के पैरामीटर लेता है, और ऑब्जेक्ट की स्थिति को बदलने और प्राप्त करने और व्यवस्थित करता है।

मॉडल के अलावा, पेटीपी जैसी इकाइयां भी वहां दिखाई दीं - ये एंडपॉइंट समूह पर सिर्फ क्लाइंट रैपर हैं, जो ओपनएपीआई समूह या तो टैग या एंडपॉइंट द्वारा।

और इस क्लाइंट के पास सभी पेन हैं जिन्हें आप वास्तविक डेटा को प्रसारित कर सकते हैं। फिर वे कुछ बैकएंड पर उड़ जाएंगे।

इस उत्पन्न ग्राहक से क्या लागू किया जाता है? दिलचस्प से - संविदात्मक दृष्टिकोण। उसके बारे में अधिक बात करते हैं।

प्रोग्रामिंग के लिए संविदात्मक दृष्टिकोण बताता है कि जब आप क्लाइंट और सर्वर के बीच इंटरैक्शन को लागू करते हैं, तो आप हमेशा कुछ नियमों पर, कॉन्ट्रैक्ट पर, चाहे वह वह डेटा हो जो क्लाइंट सर्वर को देता है, या डेटा जो क्लाइंट क्लाइंट को देता है।

इसलिए, अनुबंध का दृष्टिकोण आपको वास्तविक समय में हर बार अनुबंध के अनुपालन के लिए अपने डेटा और अपनी बातचीत की जांच करने की सलाह देता है। यदि यह अनुबंध उस डेटा की एक योजना है जिसे हम संचारित करते हैं, और हमारी अपेक्षाओं को पूरा नहीं करता है, संतुष्ट नहीं है, तो आपको यह कहने की आवश्यकता है, त्रुटि को यहीं और अभी दिखाएँ। वास्तविक बैकएंड पर न जाएं, किसी भी चार-डॉट की प्रतीक्षा न करें, लेकिन अभी कहें।

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

तो, Swagger-codegen अनुबंध दृष्टिकोण के अनुसार क्लाइंट और मॉडल बनाता है। यह आपको वास्तविक समय में कहने की अनुमति देता है: हाँ, मैं चाहता हूं कि ग्राहक अनुबंध के अनुपालन के लिए सभी डेटा की जांच करने के लिए रनटाइम में हो। और अगर अनुबंध संतुष्ट नहीं है, तो वह तुरंत ऐसा कहेगा।

हमने एक अनुबंधात्मक दृष्टिकोण के साथ कुछ प्रकार के गड्ढे-ग्राहक तैयार किए, लेकिन इसके अलावा, स्वैगर-कोडगेन ने हमारे लिए दस्तावेज स्टब्स उत्पन्न किए। वास्तव में, वे काफी सरल हैं, लेकिन वे सभी प्रत्येक मॉडल के लिए मुड़ सकते हैं।

इसके अलावा स्वैगर-कोडजेन ने कुछ प्रकार के परीक्षण स्टब उत्पन्न किए। सब कुछ ताकि आप कम से कम प्रयास के साथ उत्पन्न कोड को रोल कर सकें और इसे परीक्षणों के साथ चला सकें, निरंतर एकीकरण के साथ, एक पुस्तकालय के रूप में, सभी घंटियाँ और सीटी के साथ।

आइए हम संक्षेप में इसे फिर से पढ़ें। हमने सिर्फ एक मामले को देखा - एपीआई के लिए ग्राहकों को उत्पन्न करने का एक तरीका। महत्वपूर्ण} संविदात्मक दृष्टिकोण से। मैं यह कहना चाहूंगा: जब मैंने अपने विनिर्देशों के अनुसार एक वास्तविक पेटोर के लिए एक क्लाइंट बनाया और वास्तव में उनके बैकएंड पर गया, तो अचानक इस अनुबंधात्मक दृष्टिकोण ने अवैध डेटा को पकड़ा जो कि पेटीएसॉर द्वारा वापस कर दिया गया था।

पहले तो मैंने सोचा - वे थोड़े अजीब हैं। उन्होंने स्वयं विनिर्देश तैयार किया, और बैकएंड उनके लिए सही ढंग से काम नहीं करता है। लेकिन यह मुझे लगता है कि उन्होंने इसे इस उद्देश्य से किया था ताकि हम अनुबंध के दृष्टिकोण की शक्ति देख सकें। बहुत अधिक डेटा नहीं था, और वे स्पष्ट रूप से उत्पन्न हुए थे।

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

आप स्वैगर-कोडजेन द्वारा उत्पन्न की बजाय इन क्लाइंट्स को कॉन्फ़िगर कर सकते हैं और अपने मॉडलों का आयात लिख सकते हैं।

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

अन्य बातों के अलावा, यह आपको HTML और Confluence प्रारूप में प्रलेखन उत्पन्न करने की अनुमति देता है यदि कोई इसका उपयोग कर रहा है। OpenAPI के लिए मैं जिन उदाहरणों को दिखाना चाहता था, वे भी वहीं समाप्त हो गए।

^{_{ये सभी उपकरण स्लाइड पर नीचे दिए गए दो लिंक पर उपलब्ध हैं: openapi.tools औरgithub.com/APIs-guru/awesome-openapi3}}

मैं ओपनिंग स्पेसिफिकेशन के आसपास ट्यूनिंग समूहों को दिखाना चाहता हूं। वास्तव में, बहुत सारे उपकरण हैं। ये सिर्फ समूह हैं, अर्थात्, प्रकार के उपकरण जो आप उपयोग कर सकते हैं।

यहां महत्वपूर्ण एक विनिर्देशन से दूसरे विनिर्देशन के लिए एक कनवर्टर है। यही है, आप ब्लूप्रिंट एपीआई या ओपनएपीआई विनिर्देश से जो कुछ भी पसंद करते हैं, और इसके विपरीत उत्पन्न कर सकते हैं। प्रलेखन के लिए मॉक के लिए एक पुस्तकालय है। यही है, मैंने जो कुछ भी बात की, वह इन समूहों में परिलक्षित होगी।

एक लिंक है जिसे आप भी फॉलो कर सकते हैं। देखने जाना सुनिश्चित करें।

^{_{स्लाइड से लिंक करें}}

ओपनएपीआई के आसपास के उपकरणों के अलावा, स्वैगर के आसपास उपकरण हैं। स्वैगरहब और स्वैगर इंस्पेक्टर हैं। उन्हें नीले रंग में हाइलाइट किया गया है क्योंकि यह एक वेब-आधारित टूलकिट है। आप सीधे वहां जा सकते हैं और एक सेवा के रूप में स्वैगरहब और स्वैगर इंस्पेक्टर का उपयोग कर सकते हैं, जो वास्तव में निम्नलिखित पुस्तकालयों का सुपरपोजिशन हैं: स्वैगर-एडिटर, स्वैगर-कोडजेन, स्वैगर-यूआई। बस हम चर्चा करते हैं।

सभी पुस्तकालय पीले हैं, वे खुले स्रोत हैं, जैसा कि हमने देखा। GitHub पर है, डॉकटर के रूप में है। उपयोग।

निष्कर्ष

हमने आज क्या चर्चा की? उदाहरण के रूप में ओपनएपीआई और स्वैगर का उपयोग करके रीस्ट एपीआई विनिर्देश। मैं इस बात पर जोर देना चाहता हूं कि OpenAPI विनिर्देश का वर्णन करने का सिर्फ एक तरीका है। उनमें से बहुत। दिलचस्प लोगों में से, ब्लूप्रिंट एपीआई भी देखें। शायद किसी और को कुछ पसंद आएगा।

हमने स्वैगर भी देखा। संक्षेप में, यह, जैसा कि हमने पहले ही कहा है, विनिर्देश के चारों ओर एक सुंदर यूआई है, जो आपको इसे सुविधाजनक तरीके से देखने और पता लगाने की अनुमति देता है। वास्तव में, ये उपकरण भी कई हैं, जिनमें से लोकप्रिय रीडॉक और स्फिंक्स हैं, और वास्तव में, मार्कडाउन। यही है, आप OpenAPI से मार्कडाउन उत्पन्न कर सकते हैं, और यह सभी GitHub, GitLab - जहां भी आप चाहते हैं, में खूबसूरती से प्रदर्शित किया जाएगा।

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

^{_{स्लाइड से लिंक: FastAPI , SAFRS , रोरो}}

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

दो और ढांचे हैं: SAFRS और रोरो। बेशक, नाम जादुई हैं। वे एक अलग मॉडल पर थोड़ा काम करते हैं, आप विनिर्देश के बारे में नहीं सोचते हैं और इसे साइड इफेक्ट के रूप में प्राप्त करते हैं। इसके विपरीत, आपके पास एक विनिर्देश है जो हैंडलर चलाता है। यह, मोटे तौर पर बोल रहा है, विनिर्देश संचालित विकास है। उनके पास FastAPI जितने सितारे नहीं हैं, लेकिन मुझे लगता है कि वे ध्यान देने योग्य हैं, एक नज़र डालें।

और अंत में, हमने चर्चा की कि ओपनएपीआई और स्वैगर के उदाहरणों का उपयोग करके विनिर्देश के आसपास किस तरह की उपयोगिता है। सभी बिंदुओं के लिए मैं लिंक, यकीन है कि के लिए देखो बनाने के लिए, वहाँ दिलचस्प बातें की एक बहुत कुछ कर रहे हैं:

- OpenAPI / स्वैगर
swagger.io/docs/specification/about

- उदाहरण बाज़ पर + मार्शमैलो + apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

- OpenAPI / स्वैगर
बन्स
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

मैं पास क्या है रिपोर्ट का संदेश था? दोस्तों, विशिष्टताओं को लिखना कुछ प्रकार की नौकरशाही नहीं है। और यह उतना मुश्किल नहीं है जितना कि यह पहली नज़र में लग सकता है, बल्कि सरल है और कई उपयोगी उपकरण प्रदान करता है, जो आपके लिए शानदार अवसर प्रदान करता है।

विनिर्देशों को लिखें। सलाह देते हैं। बहुत बहुत धन्यवाद।

प्रस्तुति में सभी कोड और लिंक उपलब्ध हैं ।