OpenAPI वैलिडेटर

ब्राउज़र में चलता है वेब

OpenAPI / Swagger स्पेक में ज़रूरी फ़ील्ड, path/ऑपरेशन की संरचना, पैरामीटर परिभाषाएँ, अनसुलझे $ref संदर्भ, दोहराए गए operationId, ग़ायब रिस्पॉन्स और आम ग़लतियाँ जाँचें।

गोपनीयता: यह टूल पूरी तरह आपके ब्राउज़र में चलता है। आपका इनपुट कभी आपके डिवाइस से बाहर नहीं जाता।

OpenAPI वैलिडेटर कैसे इस्तेमाल करें

  1. स्पेसिफ़िकेशन पेस्ट करें।
  2. स्टेटस लाइन पढ़ें, फिर पहले error ठीक करें (वे टूलिंग तोड़ देते हैं) और उसके बाद warning।
  3. समीक्षा में सुधार ट्रैक करने के लिए समस्याओं की तालिका CSV में डाउनलोड करें।

OpenAPI वैलिडेटर की खूबियाँ

  • OpenAPI 3.0, 3.1 और Swagger 2.0, JSON या YAML में — लाइन तक सटीक parse एरर के साथ
  • ज़रूरी फ़ील्ड, servers/host का सिंटैक्स, path टेम्प्लेट बनाम path पैरामीटर, पैरामीटर की जगह, रिक्वेस्ट बॉडी और रिस्पॉन्स
  • दोहराए गए operationId, अनसुलझे लोकल $ref पॉइंटर, इस्तेमाल न हुए कंपोनेंट, अपरिभाषित security scheme, बिना इस्तेमाल या बिना घोषणा वाले tag
  • स्कीमा जाँच: अनजान टाइप, बिना items वाली सरणियाँ, min/max का क्रम, ऐसी required प्रॉपर्टी जो मौजूद ही नहीं, 3.0 का nullable बनाम 3.1 के type array
  • समस्याएँ गंभीरता के अनुसार क्रम में, JSON Pointer वाली जगह के साथ
  • दस्तावेज़ के आँकड़े: paths, operations, parameters, responses, schemas, security schemes, tags, servers

OpenAPI वैलिडेटर का उदाहरण

ग़लत path पैरामीटर पकड़ना

इनपुट:

paths:
  /orders/{orderId}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "404": { description: Not found }

आउटपुट:

error  #/paths/~1orders~1{orderId}/get/parameters/0/name  Path parameter "id" does not appear in the path template "/orders/{orderId}".
error  #/paths/~1orders~1{orderId}/get/parameters  Path template uses {orderId} but no path parameter "orderId" is defined.
warning  …/responses  No 2xx or default response is documented.

OpenAPI वैलिडेटर के बारे में अक्सर पूछे जाने वाले सवाल

क्या-क्या जाँचा जाता है?

ज़रूरी top-level फ़ील्ड (openapi/swagger, info.title, info.version, paths), server और host का सिंटैक्स, path टेम्प्लेट बनाम path पैरामीटर, पैरामीटर की जगह तथा required फ़्लैग, रिक्वेस्ट बॉडी, विवरण और मान्य स्टेटस कोड वाले रिस्पॉन्स, दोहराए गए operationId, अनसुलझे लोकल $ref पॉइंटर, इस्तेमाल न हुए कंपोनेंट, अपरिभाषित scheme का संदर्भ देने वाली security ज़रूरतें, tag की एकरूपता और स्कीमा कीवर्ड की समझदारी (array items, min/max क्रम, 3.0 बनाम 3.1 nullability)।

error, warning और hint में क्या अंतर है?

Error स्पेसिफ़िकेशन का उल्लंघन करते हैं और कोड जनरेटर या gateway तोड़ देंगे। Warning की अनुमति तो है, पर वे जोखिम भरे या बेमतलब होते हैं (operationId न होना, कोई 2xx रिस्पॉन्स न होना, इस्तेमाल न हुआ स्कीमा)। Hint दस्तावेज़ों की गुणवत्ता सुधारने के सुझाव हैं।

क्या यह उदाहरणों को स्कीमा के विरुद्ध जाँचता है?

नहीं। जाँच सिर्फ़ संरचना की है। किसी एक स्कीमा के विरुद्ध उदाहरण पेलोड जाँचने के लिए JSON Schema Validator टूल इस्तेमाल करें।

क्या बाहरी $ref फ़ाइलें लाई जाती हैं?

नहीं। दूसरी फ़ाइलों या URL के संदर्भ ऐसे hint के रूप में बताए जाते हैं जिनकी पुष्टि नहीं की जा सकती; बाक़ी सब कुछ आपके ब्राउज़र में ऑफ़लाइन जाँचा जाता है।

तकनीकी नोट्स

जगहें JSON Pointer (RFC 6901) के रूप में बताई जाती हैं, जिनमें स्लैश के लिए ~1 एस्केपिंग होती है, ताकि उन्हें दूसरी टूलिंग में सीधे इस्तेमाल किया जा सके। वैलिडेटर जानबूझकर संरचनात्मक और तेज़ है (एक ही pass, कोई नेटवर्क नहीं), इसलिए यह लिखते-लिखते लाइव जाँच के लिए उपयुक्त है।