OpenAPI फ़ॉर्मेटर — OpenAPI स्पेक (YAML/JSON) फ़ॉर्मेट करें

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

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

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

OpenAPI फ़ॉर्मेटर कैसे इस्तेमाल करें

कोई OpenAPI या Swagger दस्तावेज़ पेस्ट करें।
आउटपुट फ़ॉर्मैट, इंडेंटेशन और सॉर्टिंग मोड चुनें।
फ़ॉर्मेट किया हुआ दस्तावेज़ कॉपी या डाउनलोड करें (openapi.yaml / openapi.json)।

OpenAPI फ़ॉर्मेटर की खूबियाँ

2 या 4 स्पेस इंडेंटेशन के साथ JSON ↔ YAML रूपांतरण
संरचना के अनुसार सॉर्टिंग: paths, कंपोनेंट नाम और tag वर्णक्रम में, HTTP मेथड तथा top-level key तयशुदा क्रम में, रिस्पॉन्स स्टेटस कोड के अनुसार
वैकल्पिक पूर्ण canonical रूप, जिसमें हर key सॉर्ट हो जाती है
सारांश: पहचाना गया वर्शन, पहले/बाद का साइज़ और वैलिडेशन की स्थिति
ख़राब इनपुट पर लाइन तक सटीक parse एरर

OpenAPI फ़ॉर्मेटर का उदाहरण

minified JSON से सॉर्ट किए हुए YAML तक

इनपुट:

{"openapi":"3.0.3","paths":{"/b":{"get":{…}},"/a":{"post":{…},"get":{…}}},"info":{"title":"X","version":"1"}}

आउटपुट:

openapi: 3.0.3
info:
  title: X
  version: "1"
paths:
  /a:
    get: …
    post: …
  /b:
    get: …

OpenAPI फ़ॉर्मेटर के बारे में अक्सर पूछे जाने वाले सवाल

"Sort paths, methods & components" क्या करता है?

paths और कंपोनेंट नाम वर्णक्रम में आते हैं, HTTP मेथड तयशुदा क्रम में (GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH, TRACE), रिस्पॉन्स कोड संख्या के क्रम में और default सबसे आख़िर में, तथा top-level key OpenAPI के प्रचलित क्रम में। कंटेंट बिल्कुल वही रहता है, इसलिए आउटपुट diff के लिए एक स्थिर canonical रूप बन जाता है।

क्या YAML → JSON रूपांतरण बिना नुक़सान के होता है?

OpenAPI दस्तावेज़ों के लिए हाँ: वे YAML के सिर्फ़ उसी हिस्से का इस्तेमाल करते हैं जो JSON के अनुकूल है। तारीख़ और बाइनरी वैल्यू स्ट्रिंग में बदल जाती हैं, और anchor/alias खोलकर लिख दिए जाते हैं।

YAML आउटपुट में कुछ key कोट में क्यों होती हैं?

"200", "yes" या "on" जैसी key को YAML पार्सर नंबर या boolean मान लेते, इसलिए उन्हें स्ट्रिंग बनाए रखने के लिए कोट में रखा जाता है — रिस्पॉन्स कोड के लिए OpenAPI टूलिंग यही उम्मीद करती है।

क्या फ़ॉर्मेटर वैलिडेशन भी करता है?

यह संरचनात्मक वैलिडेटर चलाता है और सारांश में एरर की संख्या बताता है, पर एरर होने पर भी दस्तावेज़ फ़ॉर्मेट कर देता है, ताकि आप सुंदर बने आउटपुट में ही उसे ठीक कर सकें।

संदर्भ

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