OpenAPI वैलिडेटर: API Spec की जाँच करें

OpenAPI वैलिडेटर क्या है?

OpenAPI वैलिडेटर एक ब्राउज़र-आधारित टूल है जो OpenAPI 3.x और Swagger 2.0 स्पेसिफ़िकेशन फ़ाइलों को पार्स और वैलिडेट करता है। JSON या YAML spec पेस्ट करें, Validate पर क्लिक करें, और सेकंडों में देखें कि spec संरचनात्मक रूप से वैध है या नहीं, पाथ और ऑपरेशन की संख्या, और SDK जनरेटर और डेवलपर डॉक्यूमेंटेशन टूल्स के लिए महत्वपूर्ण गायब फ़ील्ड्स की चेतावनियों की सूची।

टूल पूरी तरह से आपके ब्राउज़र में @readme/openapi-parser लाइब्रेरी का उपयोग करके चलता है जो माँग पर लोड होती है। कोई spec कंटेंट किसी सर्वर को नहीं भेजा जाता। यह बिना अकाउंट के मुफ़्त में उपयोग करने योग्य है।

इसे वर्शन कंट्रोल में spec कमिट करने से पहले, API डॉक्यूमेंटेशन प्रकाशित करने से पहले, या किसी ऐसी spec को डीबग करते समय उपयोग करें जिसे Swagger UI, Stoplight, या SDK जनरेटर जैसा डाउनस्ट्रीम टूल रिजेक्ट कर रहा हो।

मुख्य विशेषताएँ

• OpenAPI 3.x और Swagger 2.0 सपोर्ट: वैलिडेटर दोनों फ़ॉर्मेट स्वीकार करता है। अंतर्निहित @readme/openapi-parser लाइब्रेरी OpenAPI 3.1 सहित दोनों स्पेसिफ़िकेशन वर्शन को हैंडल करती है।
• JSON और YAML इनपुट: टूल पहले JSON.parse की कोशिश करता है, फिर YAML इनपुट के लिए js-yaml पर फ़ॉलबैक करता है। आपको यह घोषित करने की ज़रूरत नहीं है कि आप कौन सा फ़ॉर्मेट उपयोग कर रहे हैं।
• सटीक एरर मैसेज के साथ संरचनात्मक वैलिडेशन: जब वैलिडेशन विफल होता है, तो पार्सर से एरर मैसेज न्यूलाइन पर विभाजित होते हैं और अलग-अलग प्रदर्शित होते हैं, प्रत्येक में जहाँ लागू हो पाथ रेफ़रेंस होता है।
• लिंटिंग चेतावनियाँ: जब एक spec संरचनात्मक रूप से वैध भी होती है, तो टूल तीन सामान्य क्वालिटी मुद्दों की जाँच करता है: गायब info.description, बिना description और summary वाले ऑपरेशन, और बिना operationId वाले ऑपरेशन (SDK जनरेशन के लिए आवश्यक)।
• Endpoint और ऑपरेशन काउंट: सफल वैलिडेशन के बाद, सारांश टाइल्स API शीर्षक, वर्शन स्ट्रिंग, कुल पाथ काउंट, और कुल ऑपरेशन काउंट दिखाती हैं।
• उदाहरण लोड करें बटन: एक न्यूनतम लेकिन पूर्ण OpenAPI 3.0 spec इंसर्ट करता है जिसमें एक /users GET endpoint है।
• वैलिडेशन हिस्ट्री: पिछली specs ब्राउज़र की IndexedDB डेटाबेस में सेव होती हैं (supporter फ़ीचर)।
• 100% क्लाइंट-साइड प्रोसेसिंग: पार्सर और वैलिडेटर ब्राउज़र में चलते हैं। Spec कंटेंट कभी आपकी मशीन से बाहर नहीं जाता।

OpenAPI वैलिडेटर का उपयोग कैसे करें

चरण 1: अपनी Spec पेस्ट करें

"OpenAPI Specification (JSON or YAML)" लेबल वाले बड़े टेक्स्टएरिया में क्लिक करें और अपना spec कंटेंट पेस्ट करें। फ़ील्ड रॉ YAML या JSON स्वीकार करता है। YAML के लिए, शीर्ष पर वर्शन डिक्लेरेशन शामिल करें (openapi: "3.0.0" या swagger: "2.0")।

यदि आप अपनी spec उपयोग करने से पहले टूल को एक्शन में देखना चाहते हैं, तो टेक्स्टएरिया के ऊपरी दाएँ कोने में "Load Example" बटन पर क्लिक करें।

चरण 2: Validate Spec पर क्लिक करें

टेक्स्टएरिया के नीचे "Validate Spec" बटन पर क्लिक करें। पार्सर चलने के दौरान बटन "Validating..." दिखाता है।

चरण 3: वैलिडेशन परिणाम की समीक्षा करें

रिज़ल्ट पैनल बटन के नीचे दो में से एक शीर्षक के साथ दिखाई देता है:

• "✓ Valid OpenAPI Specification" हरे रंग में — spec ने संरचनात्मक वैलिडेशन पास कर ली।
• "✗ Validation Failed" लाल रंग में — spec में संरचनात्मक एरर हैं जिन्हें ठीक करना होगा।

चरण 4: सारांश टाइल्स पढ़ें (वैध Specs)

वैलिडेशन पास करने वाली specs के लिए, चार सारांश टाइल्स दिखाई देती हैं:

• Title — info.title का मान
• Version — info.version का मान
• Paths — पाथ एंट्रीज़ की कुल संख्या
• Operations — HTTP मेथड+पाथ कॉम्बिनेशन की कुल संख्या

चरण 5: चेतावनियों को संबोधित करें

वैध specs पर भी तीन चेतावनी प्रकार दिखाए जाते हैं:

1. गायब info.description — spec में समग्र API विवरण नहीं है।
2. बिना description या summary वाले ऑपरेशन — काउंट के रूप में रिपोर्ट किया जाता है।
3. बिना operationId वाले ऑपरेशन — SDK जनरेटर operationId का उपयोग जनरेटेड मेथड्स के नामकरण के लिए करते हैं।

व्यावहारिक उदाहरण

उदाहरण 1: गायब आवश्यक फ़ील्ड ढूँढना

मान लीजिए आप एक Swagger 2.0 spec पेस्ट करते हैं जो एक ऐसी स्कीमा डेफ़िनिशन की $ref रेफ़रेंस करती है जो मौजूद नहीं है। वैलिडेटर रिटर्न करेगा:

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

उदाहरण 2: क्वालिटी चेतावनियों के साथ वैध Spec

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

उदाहरण 3: एक बड़ी Spec को एक नज़र में जाँचना

500-पाथ इंटरनल API spec पेस्ट करने के बाद, सारांश टाइल्स "Paths: 147" और "Operations: 312" दिखाती हैं।

टिप्स और बेस्ट प्रैक्टिसेज़

हर संरचनात्मक बदलाव के बाद वैलिडेट करें। नया पाथ जोड़ना, $ref बदलना, या स्कीमा मॉडिफ़ाई करना एरर इंट्रोड्यूस कर सकता है। वैलिडेशन दो सेकंड से कम लेता है।

operationId चेतावनियों को SDK वर्कफ़्लो के लिए ब्लॉकर मानें। बिना सेट किए छोड़ने का मतलब है कि जनरेटेड मेथड नेम पाथ से डिराइव होंगे।

उदाहरण को टेम्पलेट के रूप में उपयोग करें। बिल्ट-इन उदाहरण एक पूर्ण, वैध, न्यूनतम OpenAPI 3.0 spec है।

संरचनात्मक वैधता को सिमेंटिक शुद्धता से अलग करें। वैलिडेटर पुष्टि करता है कि आपकी spec OpenAPI स्कीमा का पालन करती है, न कि यह आपकी वास्तविक API का सटीक वर्णन करती है।

सूची के ऊपर से नीचे तक एरर ठीक करें। एक गायब स्कीमा डेफ़िनिशन पूरी spec में कैस्केडिंग $ref एरर का कारण बन सकती है।

सामान्य समस्याएँ और समस्या निवारण

"Parse error: ..." — इनपुट न तो वैध JSON है न वैध YAML। सामान्य कारण: JSON में ट्रेलिंग कॉमा, असंगत YAML इंडेंटेशन, या YAML इंडेंटेशन के लिए टैब कैरेक्टर।

Swagger UI जिसे स्वीकार करता है उस spec पर वैलिडेशन विफल होता है। Swagger UI एरर के प्रति सहनशील है। यह वैलिडेटर सख्त वैलिडेशन लागू करता है।

विवरण जोड़ने के बाद भी चेतावनियाँ दिखाई देती हैं। पुष्टि करें कि आपने info के अंदर description जोड़ी है, केवल व्यक्तिगत पाथ पर नहीं।

पहले उपयोग पर टूल धीमा लगता है। लाइब्रेरीज़ पहले वैलिडेशन क्लिक पर डायनामिकली लोड होती हैं।

गोपनीयता और सुरक्षा

OpenAPI वैलिडेटर आपकी spec को पूरी तरह ब्राउज़र में प्रोसेस करता है। @readme/openapi-parser लाइब्रेरी लोकली चलती है — कोई spec कंटेंट किसी बाहरी सर्विस या सर्वर को नहीं भेजा जाता। टूल पेज और पार्सर लाइब्रेरी लोड होने के बाद पूरी तरह ऑफ़लाइन काम करता है।

अक्सर पूछे जाने वाले प्रश्न

क्या OpenAPI वैलिडेटर मुफ़्त है? हाँ। कोई लागत, अकाउंट या उपयोग सीमा नहीं है।

कौन से OpenAPI वर्शन सपोर्टेड हैं? Swagger 2.0, OpenAPI 3.0.x, और OpenAPI 3.1.x।

क्या मैं YAML पेस्ट कर सकता हूँ या JSON होना ज़रूरी है? दोनों फ़ॉर्मेट काम करते हैं।

क्या टूल मेरे वास्तविक API endpoints को वैलिडेट करता है? नहीं। वैलिडेटर जाँचता है कि आपकी spec फ़ाइल संरचनात्मक रूप से सही है। यह आपकी spec में सूचीबद्ध सर्वरों या पाथ पर कोई HTTP रिक्वेस्ट नहीं करता।

मेरी spec यहाँ विफल क्यों होती है लेकिन Swagger UI में काम करती है? Swagger UI एरर के प्रति सहनशीलता के साथ specs रेंडर करता है। यह वैलिडेटर सख्त स्कीमा वैलिडेशन लागू करता है।

"operationId required for SDK generation" का क्या मतलब है? SDK जनरेटर operationId मानों के आधार पर जनरेटेड मेथड्स का नामकरण करते हैं। इनके बिना, जनरेटर HTTP मेथड और पाथ से नाम बनाते हैं।

क्या चेतावनियों में फ़ॉल्स पॉज़िटिव हैं? तीन चेतावनी जाँच कंसर्वेटिव हैं। info.description जाँच केवल तब ट्रिगर होती है जब फ़ील्ड अनुपस्थित या खाली है।

क्या मैं पेस्ट करने के बजाय spec फ़ाइल वैलिडेट कर सकता हूँ? टूल केवल पेस्ट किया गया टेक्स्ट स्वीकार करता है — कोई फ़ाइल अपलोड बटन नहीं है।

क्या हिस्ट्री पैनल मेरा spec कंटेंट सेव करता है? हाँ। सफल वैलिडेशन पर, टूल आपके ब्राउज़र की IndexedDB हिस्ट्री में एक एंट्री सेव करता है। हिस्ट्री आपके ब्राउज़र में लोकल है।

यदि मैं खाली spec पेस्ट करूँ तो क्या होगा? टेक्स्टएरिया खाली होने पर Validate बटन डिसेबल हो जाता है।

संबंधित टूल्स

• जल्द आ रहा है: API Mock जनरेटर — फ़्रंटएंड डेवलपमेंट में उपयोग के लिए आपकी वैलिडेटेड spec से mock रिस्पॉन्स डेटा जनरेट करें।
• जल्द आ रहा है: API डिज़ाइन सूट — OpenAPI फ़ॉर्मेट में एक्सपोर्ट करने से पहले API स्ट्रक्चर डिज़ाइन और इटरेट करें।
• JSON फ़ॉर्मेटर — वैलिडेटर में पेस्ट करने से पहले अपनी spec की JSON स्ट्रक्चर को फ़ॉर्मेट और वैलिडेट करें।

OpenAPI वैलिडेटर अभी आज़माएँ: OpenAPI वैलिडेटर