OpenAPI Diff

यह differ क्या जाँचता है — और ब्रेकिंग का वास्तव में क्या मतलब है

कोई बदलाव ब्रेकिंग तब होता है जब पुरानी स्पेसिफिकेशन के अनुसार सही ढंग से लिखा गया क्लाइंट, अपने कोड की एक भी पंक्ति बदले बिना, नई स्पेसिफिकेशन के सामने विफल हो सकता है। यही परिभाषा इस पेज के हर निर्णय को चलाती है। किसी पाथ या ऑपरेशन को हटाना ब्रेकिंग है क्योंकि मौजूदा कॉल्स के पास जाने की कोई जगह नहीं रहती। किसी रिस्पॉन्स स्थिति — सबसे बढ़कर 2xx — को हटाना ब्रेकिंग है क्योंकि क्लाइंट की त्रुटि-हैंडलिंग पुराने सेट के आसपास लिखी गई थी। कोई अनिवार्य पैरामीटर या अनिवार्य अनुरोध गुण जोड़ना ब्रेकिंग है क्योंकि कल का वैध अनुरोध अचानक अस्वीकार हो जाता है। किसी फ़ील्ड का प्रकार या प्रारूप बदलना ब्रेकिंग है क्योंकि पार्सर, वैलिडेटर और जनरेट किए गए SDK सभी घोषित प्रकार पर आधारित होते हैं। किसी enum मान को हटाना ब्रेकिंग है क्योंकि क्लाइंट उसे अब भी भेज सकता है, या ऐसा संग्रहीत डेटा रख सकता है जिसकी वह अब व्याख्या नहीं कर सकता। बाकी सब — नया एंडपॉइंट, वैकल्पिक पैरामीटर, नया रिस्पॉन्स फ़ील्ड, नया enum मान, नया स्थिति कोड — नॉन-ब्रेकिंग के रूप में रिपोर्ट होता है: पुराने क्लाइंट काम करते रहते हैं, भले ही वे नई क्षमता का उपयोग अभी न कर सकें।

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

दो इनपुट आकार स्वीकार किए जाते हैं क्योंकि पारिस्थितिकी तंत्र दोनों प्रकाशित करता है: पहले JSON आज़माया जाता है, और जब वह विफल होता है तो टेक्स्ट को YAML के रूप में पार्स किया जाता है, वह प्रारूप जिसका उपयोग अधिकांश हाथ से लिखे गए OpenAPI दस्तावेज़ करते हैं। Swagger 2.0 दस्तावेज़ भी काम करते हैं, उनके in: body पैरामीटर और प्रति-रिस्पॉन्स स्कीमा समेत। जानबूझकर कोई लाइव फ़ेचिंग नहीं है और कोई अपलोड नहीं: दस्तावेज़ पेस्ट करें या फ़ाइलें छोड़ें, बिल्कुल वैसे ही जैसे आप HAR कैप्चर के साथ करते, और तुलना तब चलती है जब आप बटन दबाते हैं — हर कीस्ट्रोक पर नहीं — इसलिए दो बड़े पेस्ट किए गए स्पेसिफिकेशन भी प्रतिक्रियाशील बने रहते हैं।

परिणाम को सजावट के रूप में नहीं, रिलीज़ गेट के रूप में उपयोग करें। समीक्षा में, ब्रेकिंग सूची ही एजेंडा है: हर प्रविष्टि को या तो सुधार, संस्करण वृद्धि, पदावनति अवधि, या यह लिखित निर्णय चाहिए कि ब्रेक जानबूझकर किया गया है और सूचित किया गया है। नॉन-ब्रेकिंग सूची चेंजलॉग का मसौदा है। Diff को JSON के रूप में निर्यात करने से आप उस निर्णय को रिलीज़ के बगल में संग्रहीत कर सकते हैं, और कॉपी करने योग्य सारांश सीधे पुल अनुरोध में चला जाता है — वही अनुशासन जो आप webhook अनुबंध बदलाव पर लागू करेंगे, जहाँ चुपचाप बदला गया पेलोड हर सब्सक्राइबर को एक साथ तोड़ देता है।

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