REST API फ्रंटएंड डेवलपर के लिए टाइप कर रहा है

आज, ब्राउज़र और सर्वर की परस्पर क्रिया का वर्णन करने के लिए व्यापक रूप से निम्नलिखित तरीकों का उपयोग किया जाता है, जैसे कि ओपनएपीआई और ग्राफक्यूएल।

इस लेख में, मैं एक सांख्यिकीय टाइप REST API बनाने और डेटा अनुरोध लिखने के लिए कोड लिखने से फ्रंट-एंड टीम को बचाने, परीक्षण को सरल बनाने और संभावित त्रुटियों की संख्या को कम करने के हमारे प्रयास के बारे में बात करूंगा।



ये उपकरण हमारी मदद करते हैं:

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

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

यदि कमांड डेटा उन डेटा प्रकारों में गलती करता है जो REST API स्वीकार / आपूर्ति करता है तो फ्रंटएंड एप्लिकेशन संकलित नहीं करेगा।

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

वैधानिक रूप से टाइप किए गए एपीआई के सभी उपरोक्त लाभ प्राप्त करने के लिए, हमें एक कोड जनरेटर का उपयोग करने की आवश्यकता है, जो ओपनएपीआई विनिर्देश के अनुसार, टाइप विवरण फाइलें उत्पन्न कर सकते हैं, टाइपस्क्रिप्ट के लिए ये * .d.ts फाइलें हैं।

हमारी परियोजना microservice वास्तुकला का उपयोग करती है और पूरे बैकएंड को .NET में लिखा जाता है, इसलिए हमने फ्रंटवार्ड / बैकएंड के लिए एपीआई क्लाइंट उत्पन्न करने के लिए NSwag का उपयोग किया। यह टूल आपको OpenAPI दस्तावेज़ जेनरेट करने की अनुमति देता है, जो तब क्लाइंट कोड जनरेट करने के लिए उपयोग किया जाता है।

आर्किटेक्चर

सामान्य तौर पर, कोड जनरेशन प्रक्रिया में कई चरण होते हैं:

• OpenAPI दस्तावेज़ जनरेशन
• OpenAPI दस्तावेज़ का उपयोग करके कोड बनाना

हमारे मामले में, बैकएंड को .Net का उपयोग करते हुए लिखा गया है और मुख्य C # विकास भाषा टूल की पसंद के कारण है। हम OpenAPI दस्तावेज़ और क्लाइंट उत्पन्न करने के लिए NSwag नामक एक ही टूल का उपयोग करते हैं।


बाकी क्लाइंट कोड जनरेट करने के लिए एक समाधान का चित्र 1 आर्किटेक्चर

आंकड़ा दिखाता है:

• माइक्रोसर्विस 1 ... एन - एपीआई प्रदान करने वाले माइक्रोसर्विसेस
• NSwag - एक microservice एपीआई कोड से एक OpenAPI दस्तावेज़ उत्पन्न (एक microservice किसी भी भाषा में लिखा जा सकता है जिसके लिए एक OpenAPI दस्तावेज़ बनाने के लिए एक उपकरण है)
• NSwag - OpenAPI दस्तावेज़ीकरण के लिए क्लाइंट API कोड जनरेट करना (ऐसे कई उपकरण हैं जिन्हें आप चुन सकते हैं जो आपकी तकनीक स्टैक को अधिक सूट करता है)
• OpenAPI डॉक्टर - OpenAPI प्रलेखन उत्पन्न
• एपीआई क्लाइंट 1 ... एन - एपीआई डेटा का उपभोग करने वाले ग्राहक (किसी भी भाषा पर लागू किया जा सकता है जो एनएसडब्ल्यू सी # और टाइपस्क्रिप्ट के लिए जनरेटर का समर्थन करता है)
• एसपीए 1 ... एन - फ्रंटेंड एप्लीकेशन, हमारे मामले में रिएक्ट (एनएसडब्ल्यू एंगुलरजेएस / एंगुलर, रिएक्ट (भ्रूण), JQuery (वादा / कॉलबैक), ऑरेलिया के लिए क्लाइंट जेनरेशन का समर्थन करता है।

क्रियाओं का क्रम इस प्रकार है:

• उपयुक्त टैग / विशेषता / डेकोरेटर के साथ एपीआई नियंत्रक को चिह्नित करें जो एपीआई की भाषा पर निर्भर करता है
• OpenAPI एपीआई कोड प्रलेखन उत्पन्न करें
• OpenAPI प्रलेखन का उपयोग करके क्लाइंट एपीआई कोड बनाएं
• एक ग्राहक उपभोक्ता एपीआई आवेदन में ग्राहक एपीआई कोड को एकीकृत करें

प्रलेखन

कोड उत्पन्न करने में सक्षम होने के लिए, हमें एपीआई नियंत्रक के स्वीकृत / लौटाए गए मानों के प्रकारों का वर्णन करने की आवश्यकता है, इस उदाहरण में, जहां C # भाषा का उपयोग किया जाता है, SwaggerOperation विशेषता का उपयोग करते हुए, हमने एक विधि को चिह्नित किया है, जो क्लाइंट कोड में सर्वर पर सभी प्रश्नावली की एक सूची लौटाएगी, क्लाइंट कोड प्राप्त करने की विधि। डेटा GetAllQuestionnaires कहा जाएगा:

[HttpGet, Route("")] [SwaggerOperation(OperationId = "GetAllQuestionnaires")] [SuccessResponse(typeof(IEnumerable<QuestionnaireViewModel>))] public IEnumerable<QuestionnaireViewModel> Get() { var surveys = _questionnaireRepository.GetAll(); return surveys.Select(QuestionnaireViewModel.ToViewModel).ToArray(); } 

एक एपीआई विधि का वर्णन करने वाला 1 उदाहरण C # कोड सूचीबद्ध करना

फिर, NSwag का उपयोग करते हुए, हम स्वचालित रूप से एक OpenAPI दस्तावेज़ बनाते हैं जिसमें सभी API समापन बिंदु होंगे जो बैकएंड कोड में संबंधित विशेषताओं के साथ चिह्नित किए गए हैं।


चित्रा 2 OpenAPI दस्तावेज़

इस प्रकार, हम हमेशा अप-टू-डेट स्वचालित रूप से हमारे एपीआई के अद्यतन प्रलेखन बनाने में कामयाब रहे।

टाइपिंग

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

हमारे उदाहरण के लिए, दस्तावेज़ में प्रश्नावली दृश्य प्रकार के बारे में जानकारी है (यहाँ पठनीयता के लिए HTML रूप में विनिर्देश प्रस्तुत किया गया है)


चित्रा 3 एक OpenAPI दस्तावेज़ में उदाहरण डेटा मॉडल

अगला कदम इस जानकारी को फ्रंटएंड एप्लिकेशन कोड को पास करना है।

कोड जनरेशन

हम क्लाइंट API कोड जनरेट करने के लिए NSwag का भी उपयोग करते हैं। इनपुट पर, यह एक OpenAPI दस्तावेज़ प्राप्त करता है और निर्दिष्ट सेटिंग्स के अनुसार क्लाइंट एपीआई कोड उत्पन्न करता है। सामने वाले के लिए, प्राप्त कोड के बगल में, हम package.json जोड़ते हैं और इसे हमारे स्थानीय npm रजिस्टर पर भेजते हैं।

जैसा कि आप बैकएंड कोड लिस्टिंग से देख सकते हैं (सूची 1 देखें), हमने विशेषता का उपयोग करके नियंत्रक विधि को चिह्नित किया

 [SwaggerOperation(OperationId = "GetAllQuestionnaires")] 

हमारे मामले में C # विशेषता में निर्दिष्ट ऑपरेशनआईड क्लाइंट विधि का नाम बन जाएगा।


चित्र 4 उत्पन्न ग्राहक एपीआई का उपयोग करने का एक उदाहरण

साथ ही, क्लाइंट को जेनरेट करने के बाद, हमें एक d.ts फाइल प्राप्त हुई जिसमें डेटा प्रकारों के संगत विवरण शामिल हैं, जो नीचे दिए गए चित्र में दिखाए गए हैं।


चित्र 5 .d.ts फ़ाइल में डेटा उदाहरण का वर्णन करें

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


चित्र 6 क्लाइंट एपीआई डेटा प्रकार की जानकारी का उदाहरण उपयोग

टाइपस्क्रिप्ट में सभी प्रासंगिक डेटा प्रकार सत्यापनकर्ता भी काम करते हैं।

नीचे दिए गए आंकड़ों में एक उदाहरण।


चित्र 7 उदाहरण क्लाइंट एपीआई डेटा प्रकार सत्यापन


चित्र 8 उदाहरण क्लाइंट API डेटा प्रकार सत्यापन

निष्कर्ष

इस दृष्टिकोण को लागू करने के बाद, हमें निम्नलिखित लाभ प्राप्त हुए:

• कम डेटा प्रकार कीड़े
• कम कोड, डिबगिंग के लिए कम श्रम, परीक्षण, समर्थन
• हमेशा microservices में से प्रत्येक के लिए सभी एपीआई तरीकों के लिए अप-टू-डेट प्रलेखन
• एपीआई स्वचालन का परीक्षण करने की क्षमता
• फ्रंटएंड और बैकएंड के लिए एकीकृत प्रकार प्रणाली

संदर्भ

• OpenAPI विशिष्टता
• NSWAG प्रोजेक्ट साइट