कार्यात्मक परीक्षणों के आधार पर ओपनएपीआई विनिर्देशों का सृजन

निश्चित रूप से, एपीआई के विकास के दौरान, प्रलेखन के साथ कठिनाइयां एक से अधिक बार दिखाई दीं: या तो यह मौजूद नहीं है, फिर यह कोड में वर्णित व्यवहार को प्रदर्शित नहीं करता है।

डेवलपर के दृष्टिकोण से, लेखन दस्तावेज़ (केवल आंतरिक) कोड लिखने से कम समय नहीं लेता है। क्या वह परिचित है? फिर बिल्ली का स्वागत है।

क्या कोई समस्या है?

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

सबकुछ ठीक होगा, लेकिन कोड लगातार बदल रहा है और बढ़ रहा है, व्यापार की जरूरतें बदल रही हैं। कोड परिवर्तन के साथ, एपीआई बदल सकते हैं, जो अनिवार्य रूप से इन पृष्ठों पर परिवर्तन की ओर जाता है। खैर, अगर यह एक पृष्ठ है और केवल 1 बार है। और अगर अधिक बदलाव हैं?

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

कुछ उपाय

कोड और इसके विनिर्देश कैसे जुड़े हो सकते हैं, इसके लिए अलग-अलग विकल्प हैं, लेकिन खुद के लिए मैं दो को अलग करता हूं:

• पहले कोड, अगला विनिर्देश
• विशिष्टता पहले, कोड अगला

मैं दूसरे के साथ शुरू करूंगा, जैसा कि उस विकल्प के साथ था जो हमारे लिए कम से कम उपयुक्त था।

विनिर्देश पहले, कोड के बारे में कोड पीढ़ी के बारे में है, विनिर्देश के आधार पर, अर्थात, जब तक आप विनिर्देश नहीं लिखते तब तक कोड मौजूद नहीं होता है।

सबसे सरल उदाहरण स्वैगर कोडगेन है।

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

कोड पहले, विनिर्देश अगला - सब कुछ सरल है, पहले हम कोड लिखते हैं, फिर विनिर्देश। लेकिन फिर सवाल उठता है - और अगर हम अनावश्यक आंदोलनों को नहीं करना चाहते हैं ताकि विनिर्देश उत्पन्न हो?

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

"आप एक प्रोग्रामर हैं," मैंने खुद से कहा, और एक छोटा प्रोटोटाइप लिखने का फैसला किया, जो मुझे यह सब नियमित कचरा नहीं लिखने देगा।

अगला कार्य करना और nth कार्यात्मक परीक्षण लिखना, मैंने महसूस किया कि हमारे पास पहले से ही विनिर्देश के लिए सभी जानकारी है।

हमारे पास कार्यात्मक परीक्षण हैं जिनमें लगभग सभी जानकारी है जो हमें चाहिए:

• क्या कहा जा रहा है
• क्या कहा जाता है (पैरामीटर, शरीर, हेडर, आदि)
• क्या परिणाम अपेक्षित है (स्थिति कोड, प्रतिक्रिया निकाय)

अपनी खुद की बाइक क्यों नहीं बनाते?

लगभग सब कुछ जो हम आमतौर पर हमारे पास मौजूद विनिर्देशों में लिखते हैं। छोटे के लिए मामला - इस मामले को कोड करें।

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

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

समस्या जो मूल रूप से हमने हल की थी। लेकिन इस समाधान के साथ कई जोखिम हैं:

• मूल्य अपनी बाइक का समर्थन करते हैं
• आवश्यक कार्यक्षमता का विस्तार
• अद्यतन और अनुवाद का सिंक्रनाइज़ेशन

इन जोखिमों को ध्यान में रखा जाना चाहिए और, यदि वे काम करना शुरू करते हैं, तो कार्रवाई करें।