OpenAPI वैलिडेटर

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

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

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

API कॉन्ट्रैक्ट टेस्टिंग क्या है?

API कॉन्ट्रैक्ट किसी इंटरफ़ेस का सहमत विवरण है — उसके एंडपॉइंट, पैरामीटर, रिक्वेस्ट व रिस्पॉन्स स्कीमा और स्टेटस कोड — जो आमतौर पर OpenAPI दस्तावेज़ के रूप में लिखा जाता है। कॉन्ट्रैक्ट टेस्टिंग सर्विस के वास्तविक रिस्पॉन्स की उस विवरण से तुलना करती है, ताकि बदला हुआ फ़ील्ड नाम या टाइप दूसरी तरफ़ को तोड़ने से पहले प्रोड्यूसर या कंज़्यूमर के पास पकड़ा जाए।

गाइड पढ़ें: API टेस्टिंग क्या है? REST API कैसे टेस्ट करें

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.
समस्याओं की तालिका में हर लोकेशन एक JSON Pointer है: root से एक-एक सेगमेंट आगे बढ़ें, हर ~1 को / पढ़ें, और ग़लत लाइन तक पहुँचें।

लोकेशन (JSON Pointer)

भाग 1:#/भाग 2:paths/भाग 3:~1orders~1{orderId}/भाग 4:get/भाग 5:parameters/भाग 6:0/भाग 7:name

YAML में यह कहाँ पहुँचता है

भाग 2:paths:
  भाग 3:/orders/{orderId}:
    भाग 4:get:
      भाग 5:parameters:
        भाग 6:- भाग 7:name: id
          in: path
          …
  1. 1डॉक्यूमेंट का root
  2. 2paths ऑब्जेक्ट
  3. 3path /orders/{orderId}key के अंदर का / ~1 के रूप में लिखा जाता है (RFC 6901), ताकि उसे विभाजक न समझा जाए
  4. 4ऑपरेशन
  5. 5उसकी पैरामीटर सूची
  6. 6पहला आइटमarray की पोज़िशन 0 से गिनी जाती हैं
  7. 7जिस फ़ील्ड में समस्या हैPath parameter "id" does not appear in the path template "/orders/{orderId}".फ़ेल

ऊपर के उदाहरण आउटपुट की पहली लोकेशन; टूल यही pointer बताता है।

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, कोई नेटवर्क नहीं), इसलिए यह लिखते-लिखते लाइव जाँच के लिए उपयुक्त है।

संदर्भ

  • OpenAPI SpecificationOpenAPI InitiativeREST API के वर्णन का मानक: पाथ, ऑपरेशन, पैरामीटर, स्कीमा, रिस्पॉन्स और सिक्योरिटी स्कीम।
  • JSON Schema SpecificationJSON SchemaJSON दस्तावेज़ की संरचना का वर्णन और वैलिडेशन करने की शब्दावली (टाइप, आवश्यक प्रॉपर्टी, फ़ॉर्मेट)।
  • RFC 9110: HTTP SemanticsIETF · 2022HTTP मेथड, हेडर फ़ील्ड, स्टेटस कोड और कंटेंट निगोशिएशन के अर्थ, वायर वर्ज़न से स्वतंत्र।