स्वैगर - आपके रैस्टफुल वेब एपीआई के लिए स्मार्ट डॉक्यूमेंटेशन - न्यूबाय के लिए जूनियर बैक-एंड डेवलपर समीक्षा

प्रस्तावना

जिस टीम में मैंने औद्योगिक कोड लिखने के क्षेत्र में अपना पहला कदम रखा था, वह C # में एक सॉफ्टवेयर उत्पाद की कार्यक्षमता के लिए एक सुविधाजनक API विकसित कर रहा था (सुविधा के लिए, आइए इसे कहते हैं, अक्षर E), जो कई वर्षों से अस्तित्व में है और बहुत ही सकारात्मक पक्ष पर बाजार में स्थापित किया है। । और यहाँ, ऐसा लगता है, युवा पडावन के पास अभी तक कोई प्रश्न नहीं होना चाहिए, लेकिन कल्पना करें कि पहले, सबसे अधिक संभावना है, निश्चित रूप से, आपने अपना वेब-एपीआई लिखा है, लेकिन यह व्यापक दर्शकों के लिए संभावना नहीं है, जिसका अर्थ है कि आप इस सिद्धांत पर रहते थे "मैं इसे स्वयं - मैं इसका उपयोग कर रहा हूं ”, और यदि कोई व्यक्ति आपके एपीआई की कार्यक्षमता में रुचि रखता है, तो आप शायद उसे विस्तृत निर्देशों के साथ एक पीडीएफ-फाइल फेंक देंगे (कम से कम मैंने ऐसा ही किया होगा)। "मैं कार्यात्मक एपीआई कहां देख सकता हूं" - मैंने टीम के नेता से पूछा, एक पाठ दस्तावेज़ के लिए लिंक प्राप्त करने की उम्मीद है। "स्वैगर को देखो," उसने जवाब दिया।

रुको, यह कैसे है कि उत्पाद लंबे समय से सफलतापूर्वक काम कर रहा है, और जिस एपीआई को आप अभी लिख रहे हैं?

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

अच्छा, तो स्वैगर क्या है और दुनिया के लिए इसकी क्या उपयोगिता है?

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



जैसा कि हम देख सकते हैं - सामान्य रूप से, स्पष्ट रूप से मॉडल, प्रतिक्रिया कोड, क्वेरी पैरामीटर सहित विधियों का एक पूरा विवरण।

और यह कैसे काम करता है?

ASP.NET कोर में स्वैगर को लागू करने के लिए बढ़िया गाइड
खरोंच से इस लेख में यहाँ है।

एपीआई तरीकों के लिए विशेष एनोटेशन का उपयोग करके प्रदर्शन को कॉन्फ़िगर करने का विचार है, यहां एक उदाहरण है:

स्वैगर कोडगेन

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

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

• API क्लाइंट: ActionScript, Ada, Apex, Bash, C # (.net 2.0, 3.5 या बाद में), C ++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http) -client, सर्वेंट), जावा (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Java के लिए Google क्लाइंट लाइब्रेरी, बाकी का आश्वासन दिया), कोटलिन, लुआ, Node.js (ES5, ES6, Google क्लोजर कम्पाइलर एनोटेशन के साथ AngularJS) ऑब्जेक्टिव-सी, पर्ल, पीएचपी, पॉवरशेल, पायथन, आर, रूबी, जंग (जंग, जंग-सर्वर, स्कैला (अक्का, http4s, swagger-async) httpclient), स्विफ्ट (2.x, 3.x, 4.x), टाइपस्क्रिप्ट (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• सर्वर स्टब्स: Ada, C # (ASP.NET Core, NancyFx), C ++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy , प्ले फ्रेमवर्क, पीकेएमएसटी), कोटलिन, पीएचपी (लुमेन, स्लिम, सिलेक्स, सिम्फनी, जेंड एक्सप्रेसिव), पायथन (फ्लास्क), नोडजेएस, रूबी (सिनात्रा, रेल्स 5), रस्ट (रस्ट-सर्वर), स्काला (फिंच, लागोम,) Scalatra)
• एपीआई प्रलेखन जनरेटर: HTML, संगम विकी
• कॉन्फ़िगरेशन फ़ाइलें: Apache2
• अन्य: jmeter

अन्य जानकारी, विशेष रूप से उपयोग के लिए निर्देश यहां प्रस्तुत किए गए हैं:
सामान्य जानकारी

और यहाँ: विवरण

निष्कर्ष

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