OpenAPI v3 (उर्फ स्वैगर 3) से कोड जनरेशन टाइपस्क्रिप्ट के लिए और न केवल

दो साल पहले, मैंने विकास शुरू किया एक और ओपनएपीआई स्पेसिफिकेशन v3 से टाइपस्क्रिप्ट (यह जीथब पर उपलब्ध है ) से एक मुफ्त कोड जनरेटर। प्रारंभ में, मैं टाइपस्क्रिप्ट में आदिम और जटिल डेटा प्रकारों की कुशल पीढ़ी बनाने के लिए सेट करता हूं, विभिन्न JSON स्कीमा सुविधाओं को ध्यान में रखते हुए , जैसे कि oneOf / anyOf / allOf , आदि। (स्वैगर के मूल समाधान में इसके साथ कुछ समस्याएं थीं)। एक और विचार था कि सामने, पीछे और सिस्टम के अन्य हिस्सों पर सत्यापन के लिए विनिर्देशों से स्कीमा का उपयोग किया जाए।

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

सामग्री

1. प्रागितिहास
2. विवरण
3. स्थापना और उपयोग
4. कोड जनरेटर का उपयोग करके अभ्यास करें
5. अनुप्रयोगों में उत्पन्न डेटा प्रकारों का उपयोग करना
6. OAS विनिर्देशन के भीतर सर्किट का अपघटन
7. नेस्टेड अपघटन
8. REST API के साथ काम करने के लिए स्वतः-जनरेट की गई सेवाएँ
   
   1. इसकी आवश्यकता क्यों है?
   2. सेवा पीढ़ी
   3. उत्पन्न सेवाओं का उपयोग करना
9. एक आफ्टरवर्ड के बजाय

प्रागितिहास

विवरण

फिलहाल, कोड जेनरेशन के समाधान में @ एनपीजी @codegena में एकीकृत तीन एनपीएम लाइब्रेरी शामिल हैं और एक आम मोनो-रिपॉजिटरी में स्थित है :

स्थापना और उपयोग

CLI से चलने वाले NodeJS स्क्रिप्ट में उपयोग करने के लिए सबसे व्यावहारिक विकल्प है। सबसे पहले आपको निर्भरता स्थापित करने की आवश्यकता है:

 npm i @codegena/oapi3ts, @codegena/ng-api-service, @codegena/oapi3ts-cli 

फिर, कोड के साथ एक js फ़ाइल (उदा। update-typings.js । update-typings.js ) update-typings.js :

 "use strict"; var cliLib = require('@codegena/oapi3ts-cli'); var cliApp = new cliLib.CliApplication; cliApp.createTypings(); // cliApp.createServices('angular'); // optional 

और तीन मापदंडों को पारित करके इसे शुरू करें:

 node ./update-typings.js --srcPath ./specs/todo-app-spec.json --destPath ./src/lib --separatedFiles true 

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

कोड जनरेटर का उपयोग करके अभ्यास करें

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

यहां तक ​​कि अगर आप कोणीय और / या NestJS से परिचित नहीं हैं, तो यह समस्या पैदा नहीं करनी चाहिए: कोड उदाहरण जो प्रदान किए जाएंगे, उन्हें सबसे टाइपस्क्रिप्ट डेवलपर्स द्वारा समझा जाना चाहिए।

यद्यपि एप्लिकेशन को अधिकतम सरलीकृत किया जाता है (उदाहरण के लिए, बैकएंड डेटा को एक सत्र में संग्रहीत करता है, और डेटाबेस में नहीं), मैंने इसमें डेटा प्रवाह और डेटा प्रकारों के पदानुक्रम को फिर से बनाने की कोशिश की जो वास्तविक अनुप्रयोग में अंतर्निहित हैं। यह लगभग 80-85% तैयार है, लेकिन "खत्म" होने में देरी हो सकती है, लेकिन अभी के लिए यह बात करना अधिक महत्वपूर्ण है कि पहले से क्या है।

अनुप्रयोगों में उत्पन्न डेटा प्रकारों का उपयोग करना

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

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

 @Controller('group') export class AppController { // ... @Put(':groupId') rewriteGroup( @Param(ParseQueryPipe) { groupId }: RewriteGroupParameters, @Body() body: RewriteGroupRequest, @Session() session ): RewriteGroupResponse<HttpStatus.OK> { return this.appService .setSession(session) .rewriteGroup(groupId, body); } // ... } 

यह पैरामीटर ( RewriteGroupParameters ), अनुरोध निकाय ( RewriteGroupRequest ) और प्रतिक्रिया निकाय ( RewriteGroupResponse<T> ) RewriteGroupResponse<T> नेस्टजेएस फ्रेमवर्क के लिए एक नियंत्रक टुकड़ा है। पहले से ही इस कोड के टुकड़े में हम टाइपिंग के लाभ देख सकते हैं:

• यदि हम नष्ट किए गए पैरामीटर groupId के नाम को भ्रमित करते हैं, तो groupId को निर्दिष्ट करने के बजाय, हमें तुरंत संपादक में एक त्रुटि मिलती है।
  
• यदि यह .appService.rewriteGroup (groupId, body) विधि में पैरामीटर टाइप किए गए हैं, तो हम पास किए गए body पैरामीटर की शुद्धता को नियंत्रित कर सकते हैं। और अगर नियंत्रक विधि या सेवा पद्धति का इनपुट डेटा प्रारूप बदलता है, तो हम तुरंत इसके बारे में जान जाएंगे। आगे देखते हुए, मैं ध्यान देता हूं कि सेवा पद्धति की इनपुट विधि का डेटा प्रकार RewriteGroupRequest से RewriteGroupRequest , लेकिन हमारे मामले में, वे एक दूसरे के समान होंगे। हालाँकि, अगर अचानक सेवा पद्धति बदल दी जाती है, और ToDoGroup बजाय ToDoGroup को स्वीकार करना शुरू कर ToDoGroupBlank , तो IDE और कंपाइलर तुरंत विसंगतियों के स्थान दिखाएगा:
  
• उसी तरह, हम लौटे परिणाम के अनुपालन को नियंत्रित कर सकते हैं। यदि एक सफल प्रतिक्रिया की स्थिति अचानक विनिर्देश में बदल जाती है और 200 बजाय 202 हो जाती है, तो हम इसके बारे में भी पता RewriteGroupResponse , क्योंकि RewriteGroupResponse एक सामान्य प्रकार के साथ एक सामान्य है :
  

अब आइए सामने वाले छोर से एक उदाहरण देखें जो एक और एपीआई विधि के साथ काम करता है:

 protected initSelectedGroupData(truth: ComponentTruth): Observable<ComponentTruth> { return this.getGroupsService.request(null, { isComplete: null, withItems: false }).pipe( pickResponseBody<GetGroupsResponse<200>>(200, null, true), switchMap<ToDoGroup[], Observable<ComponentTruth>>( groups => this.loadItemsOfSelectedGroups({ ...truth, groups }) ) ); } 

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

और हां, इस this.getGroupsService.request के कॉल पैरामीटर भी टाइप किए गए हैं। लेकिन यह उत्पन्न सेवाओं का विषय है।

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

OAS विनिर्देशन के भीतर सर्किट का अपघटन

संभवतः, पिछले उदाहरणों में, आपने ToDoGroupBlank , ToDoGroup ध्यान दिया, जिसके साथ RewriteGroupResponse और GetGroupsResponse । दरअसल, RewriteGroupResponse केवल ToDoGroup , HttpErrorBadRequest , आदि के लिए एक सामान्य उपनाम है। यह अनुमान लगाना आसान है कि ToDoGroup और HttpErrorBadRequest दोनों कंपोनेंट्स की स्कीम हैं। rehemiteGroup एंडपॉइंट (सीधे या बिचौलियों के माध्यम से) द्वारा संदर्भित स्पेसिफिकेशन ।schems सेक्शन सेक्शन:

 "responses": { "200": { "description": "Todo group saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToDoGroup" } } } }, "400": { "$ref": "#/components/responses/errorBadRequest" }, "404": { "$ref": "#/components/responses/errorGroupNotFound" }, "409": { "$ref": "#/components/responses/errorConflict" }, "500": { "$ref": "#/components/responses/errorServer" } } 

यह डेटा संरचनाओं का सामान्य अपघटन है, और इसका सिद्धांत अन्य प्रोग्रामिंग भाषाओं की तरह ही है। घटक, बदले में, विघटित भी हो सकते हैं: अन्य घटकों (पुनरावर्ती सहित), संयोजन और अन्य JSON स्कीमा सुविधाओं का उपयोग करें। लेकिन जटिलता की परवाह किए बिना, उन्हें डेटा प्रकारों के विवरण में सही ढंग से परिवर्तित किया जाना चाहिए। मैं दिखाना चाहता हूं कि आप OpenAPI में अपघटन का उपयोग कैसे कर सकते हैं, और उत्पन्न कोड कैसे दिखेगा।

अच्छी तरह से डिज़ाइन किए गए OAS विनिर्देश में घटक इसका उपयोग करने वाले अनुप्रयोगों के DDD मॉडल के साथ ओवरलैप करेंगे। लेकिन यहां तक ​​कि अगर विनिर्देश अपूर्ण है, तो आप इस पर भरोसा कर सकते हैं, अपने डेटा मॉडल का निर्माण कर सकते हैं। यह आपको अपने डेटा प्रकारों के पत्राचार पर एकीकृत उपतंत्रों के डेटा प्रकारों के साथ अधिक नियंत्रण प्रदान करेगा।

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

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

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

 "components": { "ToDoTaskBlank": { "title": "Base part of data of item in todo's group", "description": "Data about group item needed for creation of it", "properties": { "groupUid": { "description": "An unique id of group that item belongs to", "$ref": "#/components/schemas/Uid" }, "title": { "description": "Short brief of task to be done", "type": "string", "minLength": 3, "maxLength": 64 }, "description": { "description": "Detailed description and context of the task. Allowed using of Common Markdown.", "type": ["string", "null"], "minLength": 10, "maxLength": 1024 }, "isDone": { "description": "Status of task: is done or not", "type": "boolean", "default": "false", "example": false }, "position": { "description": "Position of a task in group. Allows to track changing of state of a concrete item, including changing od position.", "type": "number", "min": 0, "max": 4096, "example": 0 }, "attachments": { "type": "array", "description": "Any material attached to the task: may be screenshots, photos, pdf- or doc- documents on something else", "items": { "$ref": "#/components/schemas/AttachmentMeta" }, "maxItems": 16, "example": [] } }, "required": [ "isDone", "title" ], "example": { "isDone": false, "title": "Book soccer field", "description": "The complainant agreed and recruited more members to play soccer." } }, "ToDoTask": { "title": "Item in todo's group", "description": "Describe data structure of an item in group of tasks", "allOf": [ { "$ref": "#/components/schemas/ToDoTaskBlank" }, { "type": "object", "properties": { "uid": { "description": "An unique id of task", "$ref": "#/components/schemas/Uid", "readOnly": true }, "dateCreated": { "description": "Date/time (ISO) when task was created", "type": "string", "format": "date-time", "readOnly": true, "example": "2019-11-17T11:20:51.555Z" }, "dateChanged": { "description": "Date/time (ISO) when task was changed last time", "type": "string", "format": "date-time", "readOnly": true, "example": "2019-11-17T11:20:51.555Z" } }, "required": [ "dateChanged", "dateCreated", "position", "uid" ] } ] } } 

आउटपुट पर, हमें दो टाइपस्क्रिप्ट इंटरफेस मिलते हैं, और पहले को दूसरे द्वारा विरासत में मिलेगा:

 /** * ## Base part of data of item in todo's group * Data about group item needed for creation of it */ export interface ToDoTaskBlank { // ... imagine there are ToDoTaskBlank properties } /** * ## Item in todo's group * Describe data structure of an item in group of tasks */ export interface ToDoTask extends ToDoTaskBlank { /** * ## UID of element * An unique id of task */ readonly uid: string; /** * Date/time (ISO) when task was created */ readonly dateCreated: string; /** * Date/time (ISO) when task was changed last time */ readonly dateChanged: string; // ... imagine there are ToDoTaskBlank properties } 

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

 import { ToDoTask, ToDoTaskBlank, } from '@our-npm-scope/our-generated-lib'; export interface ToDoTaskTeaser extends ToDoTask { isInvalid?: boolean; /** * Means this task just created, has temporary uid * and not saved yet. */ isJustCreated?: boolean; /** * Means this task is saving now. */ isPending?: boolean; /** * Previous uid of task temporary assigned until * it gets saved and gets new UID from backend. */ prevTempUid?: string; } 

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

 export function downgradeTeaserToTask( taskTeaser: ToDoTaskTeaser ): ToDoTask { const task = { ...taskTeaser }; if (!task.description || !task.description.trim()) { delete task.description; } else { task.description = task.description.trim(); } delete task.isJustCreated; delete task.isPending; delete task.prevTempUid; return task; } export function downgradeTeaserToTaskBlank( taskTeaser: ToDoTaskTeaser ): ToDoTaskBlank { const task = downgradeTeaserToTask(taskTeaser) as any; delete task.dateChanged; delete task.dateCreated; delete task.uid; return task; } 

 export class ToDoTaskTeaser implements ToDoTask { // … imagine, definitions from ToDoTask are here constructor( task: ToDoTask, public isInvalid?: boolean, public isJustCreated?: boolean, public isPending?: boolean, public prevTempUid?: string ) { Object.assign(this, task); } downgradeTeaserToTask(): ToDoTask { const task = {...this}; if (!task.description || !task.description.trim()) { delete task.description; } else { task.description = task.description.trim(); } delete task.isJustCreated; delete task.isPending; delete task.prevTempUid; return task; } downgradeTeaserToTaskBlank(): ToDoTaskBlank { // … some code } } 

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

नेस्टेड अपघटन

इसलिए अब हमारे पास ToDoTask इंटरफ़ेस है और हम इसे संदर्भित कर सकते हैं। इसी प्रकार, हम ToDoTaskGroup और ToDoTaskGroupBlank का वर्णन करेंगे, और उनमें क्रमशः ToDoTask और ToDoTaskBlank प्रकार के गुण होंगे। लेकिन अब हम "टास्क ग्रुप" को दो, तीन नहीं, घटकों में तोड़ेंगे : स्पष्टता के लिए, हम ToDoGroupExtendedData में डेल्टा का वर्णन करेंगे। इसलिए मैं एक दृष्टिकोण प्रदर्शित करना चाहता हूं जिसमें एक घटक अन्य दो से बनाया गया है:

 "ToDoGroup": { "allOf": [ { "$ref": "#/components/schemas/ToDoGroupBlank" }, { "$ref": "#/components/schemas/ToDoGroupExtendedData" } ] } 

कोड पीढ़ी शुरू करने के बाद, हमें थोड़ा अलग टाइपस्क्रिप्ट निर्माण मिलता है:

 export type ToDoGroup = ToDoGroupBlank & // Data needed for group creation ToDoGroupExtendedData; // Extended data has to be obtained after first save 

चूंकि ToDoGroup अपना "निकाय" नहीं है, इसलिए कोड जनरेटर ने इसे इंटरफेस के संघ में बदलना पसंद किया। हालांकि, यदि आप अपनी स्वयं की (अनाम) योजना के साथ तीसरा भाग जोड़ते हैं, तो परिणाम दो पूर्वजों के साथ एक इंटरफ़ेस होगा (लेकिन ऐसा नहीं करना बेहतर है)। और आइए ध्यान दें कि ToDoGroupBlank इंटरफ़ेस की items प्रॉपर्टीज़ को ToDoGroupBlank एक सरणी के रूप ToDoGroupBlank टाइप किया गया है, और ToDoGroupBlank में ToDoGroupBlank पर नए सिरे से परिभाषित किया गया है। इस प्रकार, कोड जनरेटर JSON स्कीमा से TypeScipt में अपघटन की बल्कि जटिल बारीकियों को स्थानांतरित करने में सक्षम है।

 /* tslint:disable */ import { ToDoTaskBlank } from './to-do-task-blank'; /** * ## Base part of data of group * Data needed for group creation */ export interface ToDoGroupBlank { // ... items?: Array<ToDoTaskBlank>; // ... } 

 /* tslint:disable */ import { ToDoTask } from './to-do-task'; /** * ## Extended data of group * Extended data has to be obtained after first save */ export interface ToDoGroupExtendedData { // ... items: Array<ToDoTask>; } 

अच्छी तरह से, ToDoTask / ToDoTaskBlank हम अपघटन का भी उपयोग कर सकते हैं। आपने देखा होगा कि attachments प्रॉपर्टी को AttachmentMeta प्रकार के तत्वों की एक सरणी के रूप में वर्णित किया जाता है। और इस घटक को निम्नानुसार वर्णित किया गया है:

 "AttachmentMeta": { "description": "Common meta data model of any type of attachment", "oneOf": [ {"$ref": "#/components/schemas/AttachmentMetaImage"}, {"$ref": "#/components/schemas/AttachmentMetaDocument"}, {"$ref": "#/components/schemas/ExternalResource"} ] } 

यही है, यह घटक अन्य घटकों को संदर्भित करता है। चूंकि इसकी अपनी योजना नहीं है, इसलिए कोड जनरेटर एक अलग डेटा प्रकार में नहीं बनाता है ताकि संस्थाओं को गुणा न करें, लेकिन एनुमरेटेड प्रकार का एक अनाम विवरण बदल जाता है:

 /** * Any material attached to the task: may be screenshots, photos, pdf- or doc- * documents on something else */ attachments?: Array< | AttachmentMetaImage // Meta data of image attached to task | AttachmentMetaDocument // Meta data of document attached to task | string // Link to any external resource >; 

एक ही समय में, AttachmentMetaImage और AttachmentMetaDocument घटकों के लिए, गैर-अनाम इंटरफ़ेस का वर्णन किया जाता है जो कि उनका उपयोग करके फाइलों में आयात किया जाता है:

 import { AttachmentMetaDocument } from './attachment-meta-document'; import { AttachmentMetaImage } from './attachment-meta-image'; 

लेकिन AttachmentMetaImage में भी , हम एक और प्रदान की गई ImageOptions इंटरफ़ेस का लिंक पा सकते हैं, जिसका उपयोग दो बार किया जाता है, जिसमें एक अनाम इंटरफ़ेस ( अतिरिक्त रूप से रूपांतरण से परिणाम) शामिल है:

 /* tslint:disable */ import { ImageOptions } from './image-options'; /** * Meta data of image attached to task */ export interface AttachmentMetaImage { // ... /** * Possible thumbnails of uploaded image */ thumbs?: { [key: string]: { /** * Link to any external resource */ url?: string; imageOptions?: ImageOptions; }; }; // ... imageOptions: ImageOptions; } 

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

REST API के साथ काम करने के लिए स्वतः-जनरेट की गई सेवाएँ

इसकी आवश्यकता क्यों है?

यदि हम एक औसत सांख्यिकीय फ्रंट-एंड एप्लिकेशन लेते हैं जो अधिक या कम जटिल REST API के साथ काम करता है, तो इसके कोड का एक बड़ा हिस्सा API तक पहुंचने के लिए सेवाएं (या सिर्फ फ़ंक्शन) होगा। वे शामिल होंगे:

• URL और पैरामीटर मैपिंग
• मापदंडों, अनुरोध और प्रतिक्रिया का सत्यापन
• डेटा निष्कर्षण और आपातकालीन हैंडलिंग

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

 import _ from 'lodash'; import { Observable, fromFetch, throwError } from 'rxjs'; import { switchMap } from 'rxjs/operators'; // Definitions const URLS = { 'getTasksOfGroup': `${env.REST_API_BASE_URL}/tasks/\${groupId}`, // ... other urls ... }; const URL_TEMPLATES = _.mapValues(urls, url => _.template(url)); interface GetTaskConditions { isDone?: true | false; offset?: number; limit?: number; } interface ErrorReponse { error: boolean; message?: string; } // Helpers // I taken this snippet from StackOverflow only for example function encodeData(data) { return Object.keys(data).map(function(key) { return [key, data[key]].map(encodeURIComponent).join("="); }).join("&"); } // REST API functions // our REST API working function example function getTasksFromServer(groupUid: string, conditions: GetTaskConditions = {}): Observable<Response> { if (!groupUid) { return throwError(new Error('You should specify "groupUid"!')); } if (!_.isString(groupUid)) { return throwError(new Error('`groupUid` should be string!')); } if (_.isBoolean(conditions.isDone)) { // ... applying of conditions.isDone } else if (conditions.isDone !== undefined) { return throwError(new Error('`isDone` should be "true", "false" or should\'t be set!'!)); } if (offset) { // ... check of `offset` and applying or error throwing } if (limit) { // ... check of `limit` and applying or error throwing } const url = [ URL_TEMPLATES['getTasksOfGroup']({groupUid}), ...(conditions ? [encodeData(conditions)] : []) ]; return fromFetch(url); } // Using of REST API working functions function getRemainedTasks(groupUid: number): Observable<ToDoTask[] | ErrorReponse> { return getTasksFromServer(groupUid, {isDone: false}).pipe( switchMap(response => { if (response.ok) { // OK return data return response.json(); } else { // Server is returning a status requiring the client to try something else. return of({ error: true, message: `Error ${response.status}` }); } }), catchError(err => { // Network or other error, handle appropriately console.error(err); return of({ error: true, message: err.message }) }) ); } 

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

• विशिष्ट एंडपॉइंट तक पहुँचने के लिए सेवाएँ या फ़ंक्शंस ( getTasksFromServer फ़ंक्शन हमारे उदाहरण में)
• कोड के टुकड़े जो प्रक्रिया को संसाधित करते हैं ( getRemainedTasks फ़ंक्शन)

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

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

OpenAPI विषय पर लौटते हुए, हम ध्यान दें कि OAS विशिष्टताओं में पर्याप्त जानकारी हो सकती है:

• -
• URL

— . , , / — 5, 10 200, . , , : , , , RxJS- pickResponseBody , , - ; tapResponse , side-effect (tap) HTTP-. , - . , , .

, — -, . , , , "" / API "-" "" . - , "" ( ), .

, REST API Angular. , , /. . , , . , , .. .

" " . Angular-, update-typings.js :

 "use strict"; var cliLib = require('@codegena/oapi3ts-cli'); var cliApp = new cliLib.CliApplication; cliApp.createTypings(); cliApp.createServices('angular'); 

, Angular- API . , - - , . , RewriteGroupService . ApiService , , , -:

 // Typings for this API method import { RewriteGroupParameters, RewriteGroupResponse, RewriteGroupRequest } from '../typings'; // Schemas import { schema as domainSchema } from './schema.b4c655ec1635af1be28bd6'; /** * Service for angular based on ApiAgent solution. * Provides assured request to API method with implicit * validation and common errors handling scheme. */ @Injectable() export class RewriteGroupService extends ApiService< RewriteGroupResponse, RewriteGroupRequest, RewriteGroupParameters > { protected get method(): 'PUT' { return 'PUT'; } /** * Path template, example: `/some/path/{id}`. */ protected get pathTemplate(): string { return '/group/{groupId}'; } /** * Parameters in a query. */ protected get queryParams(): string[] { return ['forceSave']; } // ... } 

, JSON Schema , . , , :

 import { schema as domainSchema } from './schema.b4c655ec1635af1be28bd6'; 

, schema.b4c655ec1635af1be28bd6.ts , , .

, Angular-.

 import { ApiModule, API_ERROR_HANDLER } from '@codegena/ng-api-service'; import { CreateGroupItemService, GetGroupsService, GetGroupItemsService, UpdateFewItemsService } from '@codegena/todo-app-scheme'; @NgModule({ imports: [ ApiModule, // ... ], providers: [ RewriteGroupService, { provide: API_ERROR_HANDLER, useClass: ApiErrorHandlerService }, // ... ], // ... }) export class TodoAppModule { } 

, [])( https://angular.io/guide/dependency-injection ):

 @Injectable() export class TodoTasksStore { constructor( protected createGroupItemService: CreateGroupItemService, protected getGroupsService: GetGroupsService, protected getGroupItemsService: GetGroupItemsService, protected updateFewItemsService: UpdateFewItemsService ) {} } 

— , request , :

 return this.getGroupsService.request(null, { isComplete: null, withItems: false }).pipe( pickResponseBody<GetGroupsResponse<200>>(200, null, true), switchMap<ToDoGroup[], Observable<ComponentTruth>>( groups => this.loadItemsOfSelectedGroups({ ...truth, groups }) ) ); 

request Observable<HttpResponse<R> | HttpEvent<R>> , , . , , . , , , . RxJS- pickResponseBody .

, , , . API, . . , :

. JSON Schema . , "" - . , Sentry Kibana , . . , , .

, . , :)

एक आफ्टरवर्ड के बजाय

, . -, " " — . , , , .

— , - / ( ). , — .

.