APIs के परीक्षण और दस्तावेज़ीकरण में JSON-स्कीमा का उपयोग करना

संदर्भ API 2GIS को 4 साल के लिए विकसित किया गया है। लगभग 40 विधियां दिखाई दी हैं कि JSON और XML प्रारूप में काफी बड़ी और पदानुक्रमिक रूप से जटिल संरचनाएं लौटाती हैं। हाल ही में, मैंने अपने अनुभव को साझा करने और DevConf सम्मेलन में बोलने का फैसला किया।
रिपोर्ट के विषयों में से एक प्रतिभागियों के बीच सबसे बड़ी रुचि पैदा हुई - एपीआई जारी करने के लिए प्रारूप का परीक्षण करते समय JSON-स्कीमा का उपयोग। इस लेख में मैं आपको बताऊंगा कि यह दृष्टिकोण क्या समस्याओं को हल करता है, जिसकी सीमाएँ हैं, जो आप बॉक्स से बाहर निकलते हैं, और बोनस के रूप में क्या आता है। चलो चलते हैं!



JSON- स्कीमा XML स्कीमा प्रारूप का JSON एनालॉग है। इसका सार यह है कि यह एक घोषणात्मक रूप में दस्तावेज़ की संरचना निर्धारित करता है। परीक्षण उद्देश्यों के लिए JSON योजनाओं के उपयोग को कुछ भी नहीं रोकता है।

ऐसा लगता है, एपीआई के परीक्षण में क्या कठिनाइयाँ हो सकती हैं? यह कुछ परिष्कृत UI नहीं है। बस सोचें, अनुरोध को निष्पादित करें और परिणाम की अपेक्षा के साथ तुलना करें।
बोझिल श्रेणीबद्ध संरचनाएं जो अनुरोधों या प्रतिक्रियाओं में हो सकती हैं परेशान हैं। जब पैरामीटर 50 के आसपास होते हैं, तो सभी संभावित विशेषता मामलों को ध्यान में रखना अत्यंत समस्याग्रस्त होता है।

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

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

एपीआई प्रारूप परीक्षण

अनुरोध और प्रतिक्रिया

हम बिल्कुल एपीआई प्रतिक्रियाओं के प्रारूप के परीक्षण पर विचार करेंगे। यह सिर्फ हमारे करीब है, क्योंकि हमारा API केवल-पढ़ने के लिए है। लेकिन जब एपीआई जटिल वस्तुओं के रूप में डेटा प्राप्त करने में सक्षम होता है, तो पढ़ने के मामले में मौलिक दृष्टिकोण समान रहता है।

JSON-स्कीमा

प्रारूप

तो, यह हमारे कठिन व्यवसाय JSON-स्कीमा में हमारी मदद करेगा। प्रारूप का संक्षिप्त परिचय पहले से ही हब पर है इसलिए, हम खुद को एक तुच्छ उदाहरण के लिए प्रतिबंधित करते हैं। JSON ऑब्जेक्ट लें:

{ "a":10, "b":"boo" } 

इसकी संरचना, मापदंडों का प्रकार, प्रतिबद्धता निर्धारित करने के लिए, यह विशेष वस्तुओं के साथ पैरामीटर मानों को बदलने के लिए पर्याप्त है। हम देखते हैं:

 { "a": { "type": "number", "required": true }, "b": { "type": "string", "required": true } } 

सहमत, काफी स्पष्ट रूप से। द्वारा और बड़े, JSON- स्कीमा का लक्ष्य XML स्कीमा प्रारूप के अनुरूप होना है।

PHP कार्यान्वयन

बेशक, उत्तर का वर्णन करते समय JSON-स्कीमा का उपयोग करना आवश्यक नहीं है। प्रारूप अपेक्षाकृत युवा है, पूरी तरह से व्यवस्थित नहीं है। XML स्कीमा प्रारूप के लिए उतने पुस्तकालय और उपकरण नहीं हैं। लेकिन इतने सारे डेवलपर्स के लिए, JSON प्रारूप बहुत स्पष्ट है। और PHP की बात करें तो JSON लगभग json_encode और json_decode फ़ंक्शंस की बदौलत है।

JSON-स्कीमा प्रारूप के कार्यान्वयन विभिन्न भाषाओं के लिए हैं । जैसा कि आप देख सकते हैं, चुनाव बढ़िया नहीं है। दो संस्थानों से PHP के लिए दो पुस्तकालय हैं: MIT और बर्कले ।
लेखन के समय, MIT में आखिरी बार फरवरी 2012 में, और बर्कले जून 2013 में हुआ था। इसलिए, एक त्वरित समीक्षा ने बर्कले को चुनने के लिए प्रेरित किया।

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

मान्यता

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

 $validator = new Validator(); $validator->check(json_decode($input), json_decode($schema)); //  $input    $schema $this->assertTrue($validator->isValid(), print_r($validator->getErrors(), true)); 

सहज भी, क्या हो रहा है।

यह ध्यान दिया जाना चाहिए कि विशेष रूप से JSON योजना की जांच के लिए परीक्षण लिखने की आवश्यकता नहीं है। हमारा मानना ​​है कि एपीआई पर कार्यात्मक परीक्षण पहले ही लिखे जा चुके हैं। इसका मतलब यह है कि यदि हम फ़िल्टरिंग को सक्षम करते हैं, तो जब हम परीक्षण चलाते हैं, तो प्रतिक्रिया स्वरूप स्वचालित रूप से पृष्ठभूमि में जाँच की जाएगी। मानो चीजों के बीच। इसके अलावा कोई विशेष प्रयास नहीं, वास्तव में, लेखन सर्किट की आवश्यकता है।

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

प्रलेखन

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

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

वर्ज़निंग

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

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

JSON-स्कीमा

खैर, लेकिन अभी भी:



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

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

 "reviews_count": { "type": "number", "required": true, "meta": { "description": " ", "hide": true } } 

विचार

अब हम अपनी JSON योजना को विशेष पर सेट करते हैं। पार्सर, और यह सुरुचिपूर्ण प्रलेखन में बदल जाता है। दस्तावेज बनाते समय, न केवल हमारे स्वयं के "मेटा" टैग की सामग्री को ध्यान में रखा जाता है, बल्कि देशी स्कीमा टैग से भी जानकारी ली जाती है।

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

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

आत्म परीक्षण

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

उदाहरण

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

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

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

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

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

रिक्त मान

प्रारूप सत्यापन के बारे में बोलते हुए, किसी को यह तय करना चाहिए कि प्रतिक्रिया में खाली मूल्यों के साथ मापदंडों का क्या करना है। हम अपने लिए निम्नलिखित समझौते पर आए हैं।

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

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

निष्कर्ष

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

सच है, एक बार आपको JSON योजनाओं का उपयोग करने के लिए एक छोटा टूलकिट लिखने में निवेश करना होगा।

परीक्षणों पर समय बचाने के अलावा, एपीआई में पिछड़े संगतता को बनाए रखना आसान है, जैसा कि एपीआई प्रारूप स्पष्ट रूप से एक JSON योजना में व्यक्त किया गया है। और प्रलेखन का भारी बोझ हल्का कैरी-ऑन हो जाता है।