Tool overview
OpenAPI वैलिडेटर क्या है?
OpenAPI वैलिडेटर एक टूल है जो आपको openAPI और Swagger दस्तावेज़ lint करें — त्रुटि, चेतावनी, path कवरेज में मदद करता है।
OpenAPI वैलिडेटर क्यों उपयोग करें?
जब आपको openAPI और Swagger दस्तावेज़ lint करें — त्रुटि, चेतावनी, path कवरेज की ज़रूरत हो तो यह पठनीयता और गति बढ़ाता है — पूरी तरह ब्राउज़र में, बिना सर्वर अपलोड के।
मुख्य विशेषताएँ
क्लाइंट-साइड गोपनीयता, तत्काल परिणाम और एक-क्लिक कॉपी। OpenAPI और Swagger दस्तावेज़ lint करें — त्रुटि, चेतावनी, path कवरेज
उपयोग कैसे करें
ऊपर दिए टूल से सटीक परिणाम पाने के लिए इन चरणों का पालन करें।
- Paste OpenAPI 3 या Swagger 2 JSON/YAML.
- Review status: VALID, VALID WITH WARNINGS, या INVALID.
- Fix errors और pipe cleaned spec into Kiota SDK Engine.
Validation Checks
इस उपयोगिता के लिए मान्य उदाहरण, सामान्य अमान्य इनपुट और बार-बार होने वाली त्रुटियाँ देखें।
OpenAPI Validator गाइड — यहाँ से शुरू करें
यह पृष्ठ DevUtilities के साथ ब्राउज़र में OpenAPI और Swagger दस्तावेज़ों को lint करने की प्रामाणिक गाइड है। पढ़ते समय ऊपर एक स्पेक पेस्ट करें, या नीचे किसी विषय पर जाएँ। सत्यापन स्थानीय रहता है — दस्तावेज़ कभी अपलोड नहीं होते। जब lint हरा हो, तो readiness स्कोर और generate कमांड पूर्वावलोकन के लिए Kiota SDK Engine में पाइप करें।
OpenAPI Validator क्या करता है
OpenAPI Validator OpenAPI 3 और Swagger 2 JSON/YAML के लिए क्लाइंट-साइड लिंटर है। यह VALID, VALID WITH WARNINGS या INVALID को पथ-जागरूक निदान के साथ रिपोर्ट करता है ताकि SDK जनरेशन या गेटवे आयात से पहले ब्लॉकर ठीक किए जा सकें।
आपको क्या मिलता है
- OpenAPI 3.x और Swagger 2 दस्तावेज़ (JSON या YAML) पार्स करता है
- स्थिति बैनर: VALID / VALID WITH WARNINGS / INVALID
- संस्करण कुंजियाँ, paths कवरेज, servers और सामान्य संरचनात्मक समस्याओं की जाँच
- केवल स्थानीय lint — आंतरिक API स्पेक के लिए सुरक्षित
- codegen readiness के लिए Kiota SDK Engine तक सीधी हैंडऑफ़
इस टूल का उपयोग तब करें जब
- Microsoft Kiota या अन्य जनरेटर से पहले तेज़ प्री-फ़्लाइट चाहिए
- CI या PR चेकलिस्ट को कमिटेड स्पेक का पठनीय lint चाहिए
- आपको Swagger 2 फ़ाइल विरासत में मिली है और OpenAPI 3 काम से पहले माइग्रेशन चेतावनियाँ चाहिए
- डुप्लिकेट operationId या टूटे $ref codegen तोड़ते रहते हैं
संबंधित टूल तब पसंद करें जब
- पूर्ण Kiota readiness स्कोर, भाषा मैट्रिक्स और CLI बिल्डर चाहिए → Kiota SDK Engine
- केवल JSON पेलोड सुंदर करने हैं → JSON Formatter
- मॉक प्रतिक्रिया arrays चाहिए → JSON Generator
Kiota और अन्य codegen से पहले तैयारी
कोड जनरेटर (विशेषकर Kiota) उन संरचनात्मक समस्याओं पर ज़ोर से विफल होते हैं जिन्हें सामान्य YAML नज़र चूक जाती है। पहले यहाँ lint करें, फिर जनरेटर-विशिष्ट readiness के लिए Kiota SDK Engine खोलें।
codegen से पहले साफ़ करने योग्य ब्लॉकर
- डुप्लिकेट या अनुपस्थित operationId (मेथड नाम टकराव)
- सफलता स्टेटस कोड पर गायब या खाली responses
- components में अमान्य या लटकता $ref
- गायब openapi/swagger संस्करण कुंजी या खाली paths ऑब्जेक्ट
- वृत्ताकार schema संदर्भ (अक्सर अगले चरण में Kiota में दिखते हैं)
चेतावनियाँ जिन्हें आप स्थगित कर सकते हैं
- गायब servers[] — क्लाइंट को --base-url ओवरराइड की आवश्यकता हो सकती है
- Swagger 2 माइग्रेशन नोट्स — नई API के लिए OpenAPI 3 पसंद करें
- कम विवरण — दस्तावेज़ गुणवत्ता, पार्स ब्लॉकर नहीं
चरण-दर-चरण: पेस्ट करें, lint करें, ठीक करें, पाइप करें
SDK जनरेट करने से पहले पहली वॉकथ्रू।
- इनपुट पैनल में OpenAPI 3 या Swagger 2 को JSON या YAML के रूप में पेस्ट करें।
- स्थिति पढ़ें: VALID, VALID WITH WARNINGS, या INVALID।
- निदान सूची की हर त्रुटि ठीक करें — operationId, responses और $ref विफलताओं से शुरू करें।
- जब तक स्थिति VALID न हो या केवल स्वीकार्य चेतावनियाँ शेष न रहें, दोबारा lint करें।
- साफ़ स्पेक को Kiota SDK Engine में पाइप करें — स्कोर, भाषा पूर्वावलोकन और kiota generate कमांड के लिए।
- ठीक किए दस्तावेज़ को कमिट करें और वैकल्पिक रूप से इस lint को PR चेकलिस्ट आइटम बनाएँ।
उपयोग मामला: CI / PR lint गेट
पुल अनुरोध OpenAPI संपादन मर्ज करते हैं जो बाद में रात्रिकालीन SDK पुनर्जनन तोड़ देते हैं। समीक्षक आँख से डुप्लिकेट operationId नहीं देख सकते।
यह टूल इसे कैसे हल करता है
- समीक्षा के दौरान PR का OpenAPI दस्तावेज़ वैलिडेटर में पेस्ट करें।
- स्वीकृत करने से पहले VALID (या केवल दस्तावेज़ीकृत चेतावनियाँ) आवश्यक करें।
- समीक्षा थ्रेड में निदान पाठ के साथ डुप्लिकेट operationId और टूटे $ref बताएँ।
- मर्ज के बाद उसी दस्तावेज़ पर CI में Kiota चलाएँ।
मानव-गति lint गेट जो जनरेटर जैसी विफलताएँ पकड़ता है — स्पेक अपलोड किए बिना।
उपयोग मामला: Kiota से पहले प्री-SDK जाँच
एक टीम kiota generate चलाने वाली है और चाहती है कि दस्तावेज़ नामकरण या $ref मुद्दों पर विफल न हो।
यह टूल इसे कैसे हल करता है
- INVALID साफ़ होने तक यहाँ दस्तावेज़ lint करें।
- Kiota SDK Engine में पाइप करें और OpenAPI Readiness स्कोर देखें।
- Kiota निदान में शेष Kiota-विशिष्ट समस्याएँ (वृत्ताकार refs, nullable शैली) ठीक करें।
- जब readiness स्वीकार्य हो तो जनरेटेड CLI कमांड कॉपी करें।
दो-चरणीय स्थानीय वर्कफ़्लो: संरचनात्मक lint → Kiota readiness → आपकी मशीन पर generate।
उपयोग मामला: Swagger 2 माइग्रेशन चेतावनियाँ
पुराना Swagger 2 JSON अभी भी गेटवे चलाता है। हितधारक Kiota अपनाने से पहले OpenAPI 3 चाहते हैं।
यह टूल इसे कैसे हल करता है
- Swagger 2 दस्तावेज़ पेस्ट करें और माइग्रेशन चेतावनियाँ नोट करें।
- संरचनात्मक INVALID समस्याएँ ठीक करें जो किसी भी कनवर्टर को रोकेंगी।
- नई सुविधाओं के लिए OpenAPI 3 माइग्रेशन योजना बनाएँ; गेटेड रहते हुए ही Swagger 2 रखें।
- Kiota से पहले OpenAPI 3 परिणाम दोबारा lint करें।
स्पष्ट संकेत कि Swagger 2 चेतावनियों के साथ पार्स होता है — नए SDK काम के लिए OpenAPI 3 पसंद करें।
सुधार: डुप्लिकेट operationId
जनरेटर operationId से क्लाइंट मेथड नाम देते हैं। डुप्लिकेट टकराव पैदा करते हैं।
ऐसा क्यों होता है
दो या अधिक ऑपरेशन एक ही operationId साझा करते हैं, या जहाँ जनरेटर माँगता है वहाँ operationId गायब है।
निदान
दस्तावेज़ में दोहराए गए operationId मान खोजें। Kiota और यह लिंटर दोनों टकराव फ़्लैग करते हैं — SDK इंजन खोलने से पहले यहाँ ठीक करें।
सुधार
- हर ऑपरेशन को अद्वितीय operationId दें (क्रिया + संसाधन सामान्य पैटर्न है)।
- संपादन के दौरान कॉपी किए गए अप्रयुक्त डुप्लिकेट paths हटाएँ।
- आंशिक SDK के लिए काटते समय उत्पादन ID बेतरतीब न बदलें — टकराने वाले paths हटाएँ।
नाम बदलने के बाद दोबारा lint करें और Kiota readiness फिर जाँचें — पूर्वावलोकन में मेथड नाम बदलेंगे।
सुधार: गायब या खाली responses
उपयोग योग्य responses के बिना ऑपरेशन टाइप्ड क्लाइंट जनरेशन तोड़ते हैं।
ऐसा क्यों होता है
एक path ऑपरेशन responses छोड़ देता है, या सफलता responses में schema के बिना खाली content {} होता है।
निदान
प्रत्येक ऑपरेशन की responses मैप में 200/201 (या default) प्रविष्टियाँ जाँचें और सुनिश्चित करें कि content schema हल होते हैं।
सुधार
- कम से कम एक सफलता response जोड़ें जिसमें application/json (या प्रासंगिक) मीडिया प्रकार हो।
- content खाली छोड़ने के बजाय $ref से components.schemas की ओर इंगित करें।
- जब क्लाइंट को संभालना हो तो त्रुटि responses (4xx/5xx) दस्तावेज़ करें — छोड़ने पर चेतावनियाँ रह सकती हैं।
सुधार: अमान्य या लटकता $ref
अमान्य $ref पॉइंटर lint और codegen के दौरान schema समाधान रोकते हैं।
ऐसा क्यों होता है
एक $ref गायब घटक को लक्ष्य करता है, गलत JSON Pointer उपयोग करता है, या ऐसा चक्र बनाता है जिसे रिज़ॉल्वर नहीं खोल सकता।
निदान
प्रत्येक असफल $ref पथ को components.schemas / parameters / responses तक फ़ॉलो करें। पुष्टि करें कि लक्ष्य कुंजी मौजूद है और वर्तनी मेल खाती है।
सुधार
- गायब घटक लक्ष्य की मरम्मत करें या फिर बनाएँ।
- $ref स्ट्रिंग को #/components/... पॉइंटर में सामान्यीकृत करें।
- उथले DTO निकालकर वृत्ताकार संदर्भ तोड़ें (अगला Kiota का वृत्ताकार-ref गाइड लागू होता है)।
VALID बनाम VALID WITH WARNINGS बनाम INVALID
दस्तावेज़ बदलने से पहले बैनर की व्याख्या करें।
सत्यापन स्थिति
| स्थिति | अर्थ | अगला कदम |
|---|---|---|
| VALID | कोई अवरोधक संरचनात्मक समस्या नहीं मिली | Kiota में पाइप या कमिट सुरक्षित |
| VALID WITH WARNINGS | पार्स होता है पर गैर-अवरोधक समस्याएँ हैं (जैसे servers, Swagger 2) | चेतावनियाँ समीक्षा करें; स्वीकार्य हों तो आगे बढ़ें |
| INVALID | अवरोधक त्रुटियाँ मौजूद | codegen से पहले निदान ठीक करें |
साफ specs को Kiota SDK Engine में पाइप करें
OpenAPI Validator और Kiota SDK Engine पूरक हैं। यहाँ संरचनात्मक स्वास्थ्य lint करें; जनरेटर readiness, भाषा मैट्रिक्स, एंडपॉइंट चयन और CLI कमांड निर्यात के लिए Kiota उपयोग करें।
- VALID के बाद साफ़ स्पेक को Kiota SDK Engine में पाइप या पेस्ट करें।
- डुप्लिकेट operationId, वृत्ताकार $ref और nullable शैली समस्याओं के लिए Kiota निदान उपयोग करें।
- Kiota Generate चरण से kiota generate कॉपी करें — फ़ाइल उत्सर्जन अभी भी स्थानीय Kiota CLI से चलता है।
- दोनों टूल क्लाइंट-साइड रखें ताकि आंतरिक API अनुबंध ब्राउज़र न छोड़ें।
OpenAPI lint सर्वोत्तम अभ्यास
- स्वीकृत करने से पहले हर OpenAPI PR पर lint करें।
- नई API के लिए OpenAPI 3 पसंद करें; Swagger 2 को माइग्रेशन चेतावनियों वाला विरासत मानें।
- operationId अद्वितीय और स्थिर रखें — नाम बदलने से जनरेटेड क्लाइंट हिलते हैं।
- सफलता responses को हमेशा हल करने योग्य schema दें।
- Kiota खोलने से पहले INVALID साफ़ करें; फिर जनरेटर-विशिष्ट readiness के लिए Kiota।
- जब यह स्थानीय पथ पर्याप्त हो तो आंतरिक स्पेक तृतीय-पक्ष lint SaaS पर अपलोड न करें।
अक्सर पूछे जाने वाले प्रश्न
सामान्य डिबगिंग समस्याओं और डेटा गोपनीयता से जुड़े विस्तृत उत्तर।
संबंधित टूल
इस टूल के पूरक अन्य संबंधित उपयोगिताएँ देखें।
आधिकारिक दस्तावेज़ और संदर्भ
इस उपयोगिता के लिए प्रामाणिक विनिर्देश और प्लेटफ़ॉर्म दस्तावेज़।