💇 🤸🏽 ♐️ अस्पताल के पूर्व का हॉटफ़िक्स या “अरे स्वैगर! मेरी गलतियाँ कहाँ हैं? ” 🧑🏾‍🤝‍🧑🏾 ♂️ 👨‍👨‍👦

क्या आपने कभी मास्टर को हॉटफ़िक्स के दौरान समायोजित किया है? नहीं! लेकिन मैं सफल रहा!

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

और जावा 8 से वैकल्पिक नहीं के बारे में थोड़ा अधिक।

इंटरैक्टिव डॉक्यूमेंटेशन बनाने के लिए हम स्वैगर का उपयोग करते हैं।

इसलिए, जब आप एपीआई में एक विधि बनाते हैं, तो:

0. आवश्यक टिप्पणियां जोड़ें, जैसे @RequestMapping और इतने पर।

1. @ErrorCodes (हमारा अपना एनोटेशन) जोड़ें, और स्ट्रिंग त्रुटि कोड सूचीबद्ध करें जो प्रतिक्रिया में यह विधि वापस आ सकती है।

2. नोट फ़ील्ड में इन त्रुटियों के बारे में @ApiOperation और डुप्लिकेट जानकारी जोड़ें।

3. बाकी एनोटेशन जोड़ें ...

यह कुछ इस तरह दिखता था (अनावश्यक और सरलीकृत हटा दिया गया):

@ApiOperation( value = "Some description.", notes = "List of possible error codes:" + "<ul>" + " <li>sms.verification.code.fail</li>" + "</ul>") @PostMapping("/security/confirmation/check") @ErrorCodes(values = {"sms.verification.code.fail"}) public ResponseDto check(@ApiParam @RequestBody @Valid RequestDto request) {... }

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

शायद इसे लेना और आगे बढ़ना सामान्य होगा। दूसरों के लिए शेल्फ पर एक चेक मार्क लगाएं जैसा कि वे कहते हैं, मैक्स, सावधान रहें, इस पर ध्यान दें ...

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

स्टेप 1. कोई यहां था ...

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

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

कार्रवाई 2. यह काम करता है!

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

प्लगइन। संस्करण 1

 @Component @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1) public class SwaggerErrorCodesConfiguration implements OperationBuilderPlugin { /** * Appends note of operation. Adds error codes to note of operation. * <code> * <h3>List of possible errors:</h3> * <ul> * <li>error.code.1</li> * <li>error.code.2</li> * <li>error.code.3</li> * </ul> * </code> * @param context operation context */ @Override public void apply(OperationContext context) { Method operationMethod = context.getHandlerMethod().getMethod(); // Check method is annotated by @ErrorCodes ErrorCodes errorCodes = findAnnotation(operationMethod, ErrorCodes.class); if (errorCodes == null) { return; } StringBuilder errorCodesNote = new StringBuilder(); errorCodesNote.append("<h3>List of possible errors:</h3>"); errorCodesNote.append("<ul>"); for (String errorCode: errorCodes.values()) { errorCodesNote.append("<li>").append(errorCode).append("</li>"); } errorCodesNote.append("</ul>"); // Write new version of notes. context.operationBuilder().notes(errorCodesNote.toString()).build(); } @Override public boolean supports(DocumentationType delimiter) { return SwaggerPluginSupport.pluginDoesApply(delimiter); } }

मैंने एक ऐसी विधि के साथ परीक्षण शुरू किया जो @ApiOperation में नोटों के लिए कोई मान निर्दिष्ट नहीं करता है।

 @ApiOperation(value = "Some description.") @PostMapping("/security/confirmation/check") @ErrorCodes(values = {"sms.verification.code.fail"}) public ResponseDto check(@ApiParam @RequestBody @Valid RequestDto request) { ... }

लॉन्च और ... परिणाम! हुर्रे, यह काम करता है! नोटों में sms.verification.code.fail स्ट्रिंग कोड दिखाई दिया!

चरण 3. यह काम करता है, लेकिन यह काम नहीं करता है।

फिर मैंने नोट्स में कुछ शब्द जोड़े और मुझे यह कोड मिला:

 @ApiOperation(value = "Some description.", notes = "Some initial note.") @PostMapping("/security/confirmation/check") @ErrorCodes(values = {"sms.verification.code.fail"}) public ResponseDto check(@ApiParam @RequestBody @Valid RequestDto request) { ... }

फिर से लॉन्च किया गया। नतीजा ... अप्रत्याशित था। प्रलेखन (O_o) बनाते समय स्प्रिंगफॉक्स प्लगइन नोटों को अधिलेखित कर देता है!

मैं देखता हूं कि कैसे संदर्भ.प्रवेशनब्यूब्रल ()। नोट्स (स्ट्रिंग) काम करता है और मैं निम्नलिखित देखता हूं:

 public OperationBuilder notes(String notes) { this.notes = (String)BuilderDefaults.defaultIfAbsent(notes, this.notes); return this; }

उम ... ठीक है, फिर हम नोटों का वर्तमान मूल्य लेंगे और त्रुटि कोड जोड़ेंगे। यह @ApiOperation एनोटेशन प्राप्त करने के लिए बना हुआ है, वांछित मूल्य लें और जो मैं खुद बना रहा हूं उसे जोड़ दें।

तो, अंतिम संस्करण ( gist.github.com पर उपलब्ध है )

प्लगइन। संस्करण 2

 @Component @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1) public class SwaggerErrorCodesConfiguration implements OperationBuilderPlugin { /** * Appends note of operation. Adds error codes to note of operation. * <code> * <h3>List of possible errors:</h3> * <ul> * <li>error.code.1</li> * <li>error.code.2</li> * <li>error.code.3</li> * </ul> * </code> * @param context operation context */ @Override public void apply(OperationContext context) { Method operationMethod = context.getHandlerMethod().getMethod(); // Check method is annotated by @ApiOperation ApiOperation apiOperation = findApiOperationAnnotation(operationMethod).orNull(); if (apiOperation == null) { return; } // Check method is annotated by @ErrorCodes ErrorCodes errorCodes = findAnnotation(operationMethod, ErrorCodes.class); if (errorCodes == null) { return; } // Prepend notes by using current value of notes in @ApiOperation StringBuilder errorCodesNote = new StringBuilder(apiOperation.notes()); errorCodesNote.append("<h3>List of possible errors:</h3>"); errorCodesNote.append("<ul>"); for (String errorCode: errorCodes.values()) { errorCodesNote.append("<li>").append(errorCode).append("</li>"); } errorCodesNote.append("</ul>"); // Write new version of notes. context.operationBuilder().notes(errorCodesNote.toString()).build(); } @Override public boolean supports(DocumentationType delimiter) { return SwaggerPluginSupport.pluginDoesApply(delimiter); } }

अब तो जैसा होना चाहिए था, वैसा हो गया!

चरण 4. जावा 8 से वैकल्पिक के बारे में क्या?

प्लगइन पर काम की बहुत शुरुआत में, मैं समझ नहीं सका कि वैकल्पिक के साथ क्या गलत था, जो एनोटेशन की खोज करते समय वापस आ जाता है। इस वर्ग में मानक तरीके नहीं थे जो कि java.util.Optional के साथ काम करने के लिए उपयोग किए जाते हैं। उदाहरण के लिए, कोई ifPresent विधि नहीं है, लेकिन एक orNull विधि है।
यह पता चला कि स्प्रिंगफॉक्स अमरूद से वैकल्पिक का उपयोग करता है।

टीएल, डॉ

मैंने स्प्रिंगफॉक्स के लिए एक प्लगइन लिखा था, जो एक स्प्रिंग घटक है और हमारे @ErrorCodes एनोटेशन से मूल्यों को पढ़ने के लिए प्रलेखन पीढ़ी के चरण में कहा जाता है।

प्लगइन कोड

 @Component @Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1) public class SwaggerErrorCodesConfiguration implements OperationBuilderPlugin { /** * Appends note of operation. Adds error codes to note of operation. * <code> * <h3>List of possible errors:</h3> * <ul> * <li>error.code.1</li> * <li>error.code.2</li> * <li>error.code.3</li> * </ul> * </code> * @param context operation context */ @Override public void apply(OperationContext context) { Method operationMethod = context.getHandlerMethod().getMethod(); // Check method is annotated by @ApiOperation ApiOperation apiOperation = findApiOperationAnnotation(operationMethod).orNull(); if (apiOperation == null) { return; } // Check method is annotated by @ErrorCodes ErrorCodes errorCodes = findAnnotation(operationMethod, ErrorCodes.class); if (errorCodes == null) { return; } // Prepend notes by using current value of notes in @ApiOperation StringBuilder errorCodesNote = new StringBuilder(apiOperation.notes()); errorCodesNote.append("<h3>List of possible errors:</h3>"); errorCodesNote.append("<ul>"); for (String errorCode: errorCodes.values()) { errorCodesNote.append("<li>").append(errorCode).append("</li>"); } errorCodesNote.append("</ul>"); // Write new version of notes. context.operationBuilder().notes(errorCodesNote.toString()).build(); } @Override public boolean supports(DocumentationType delimiter) { return SwaggerPluginSupport.pluginDoesApply(delimiter); } }

अस्पताल के पूर्व का हॉटफ़िक्स या “अरे स्वैगर! मेरी गलतियाँ कहाँ हैं? ”

स्टेप 1. कोई यहां था ...

कार्रवाई 2. यह काम करता है!

चरण 3. यह काम करता है, लेकिन यह काम नहीं करता है।

चरण 4. जावा 8 से वैकल्पिक के बारे में क्या?

टीएल, डॉ

More articles: