OpenAPI / AsyncAPI

एक OpenAPI या AsyncAPI स्पेक जोड़ें और एक नेटिव API संदर्भ पाएँ — प्रति ऑपरेशन एक वास्तविक पृष्ठ, आपके साइडबार और खोज में।

Blume को किसी OpenAPI स्पेक पर इंगित करें और यह एक नेटिव API संदर्भ तैयार करता है: प्रति ऑपरेशन एक वास्तविक पृष्ठ, टैब-स्कोप वाले साइडबार में टैग के अनुसार समूहीकृत, स्कीमा तालिकाओं, अनुरोध/प्रतिक्रिया उदाहरणों, जनरेट किए गए कोड नमूनों और एक इंटरैक्टिव Try it पैनल के साथ। चूँकि प्रत्येक ऑपरेशन एक असली Blume पृष्ठ है, इसे अपना स्वयं का URL मिलता है, यह साइट खोज और llms.txt में दिखाई देता है, और इसे एक Open Graph छवि मिलती है — ठीक वैसे ही जैसे किसी भी हाथ से लिखे दस्तावेज़ को। नीचे दिया गया कॉन्फ़िग उदाहरण के तौर पर Blume को सार्वजनिक Petstore स्पेक पर इंगित करता है।

openapi: {
  enabled: true,
  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
}

यह संदर्भ को /reference पर माउंट करता है (एक अवलोकन पृष्ठ) और प्रत्येक ऑपरेशन को /reference/<tag>/<operation> पर। spec या तो एक http(s) URL होता है या आपकी परियोजना में किसी स्थानीय फ़ाइल का पथ। Blume इसे Scalar के OpenAPI पार्सर से पार्स करता है — Swagger 2.0 और OpenAPI 3.0 स्पेक स्वचालित रूप से 3.1 में अपग्रेड कर दिए जाते हैं। इसके बजाय किसी GraphQL API का दस्तावेज़ीकरण कर रहे हैं? GraphQL संदर्भ देखें।

यह संदर्भ स्वयं कोई हेडर टैब नहीं जोड़ता। इसे सामने लाने के लिए, किसी नेविगेशन टैब को इसके रूट पर इंगित करें — इससे नेटिव रेंडरर के लिए ऑपरेशन साइडबार का दायरा भी तय होता है:

navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}

एक स्थानीय स्पेक

सापेक्ष पथ आपकी परियोजना के रूट से हल किया जाता है और बिल्ड के समय पढ़ा जाता है। JSON और YAML दोनों काम करते हैं:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
}

रूट

route यह नियंत्रित करता है कि संदर्भ कहाँ माउंट हो — अवलोकन पृष्ठ और प्रत्येक ऑपरेशन रूट का उपसर्ग (और वह रूट जिस पर आप नेविगेशन टैब इंगित करते हैं):

openapi: {
  enabled: true,
  route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
  spec: "./openapi.yaml",
}

कोड नमूने और स्कीमा

codeSamples चुनता है कि प्रति ऑपरेशन कौन-सी भाषाएँ रेंडर हों (अंतर्निहित: curl, js, python); expandSchemas नेस्टेड स्कीमा पंक्तियों को सिकुड़ी हुई के बजाय विस्तारित अवस्था में शुरू करता है:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  codeSamples: ["curl", "js"],
  expandSchemas: true,
}

“Try it” प्लेग्राउंड

नेटिव रूप से रेंडर किए गए ऑपरेशन पृष्ठ डिफ़ॉल्ट रूप से एक इंटरैक्टिव Try it पैनल के साथ आते हैं। Blume फ़ॉर्म को ऑपरेशन से ही जनरेट करता है: प्रत्येक पथ, क्वेरी और हेडर पैरामीटर के लिए एक इनपुट, अनुरोध-बॉडी स्कीमा से बना एक बॉडी संपादक, और सब कुछ स्पेक के उदाहरणों से पहले से भरा हुआ। एक सर्वर चयनकर्ता स्पेक के servers सूचीबद्ध करता है, साथ ही किसी अन्य बेस URL के लिए एक मुक्त-पाठ फ़ील्ड, और प्रामाणीकरण इनपुट ऑपरेशन की हल की गई सुरक्षा से मेल खाते हैं — bearer टोकन, API कुंजी और basic क्रेडेंशियल, तथा OAuth2 के लिए एक टोकन पेस्ट फ़ील्ड (एक एक्सेस टोकन साथ लाएँ; Blume फ़्लो नहीं चलाता)।

पैनल और कोड नमूने एक-दूसरे के साथ कदम मिलाकर चलते हैं: फ़ॉर्म में टाइप किए गए मान जनरेट किए गए नमूनों को लाइव अपडेट करते हैं, इसलिए कॉपी की गई curl कमांड हमेशा ठीक उसी से मेल खाती है जो Send करता। और यह रास्ते से हटकर रहता है — पैनल सर्वर-रेंडर होकर सिकुड़ी अवस्था में आता है, और इसका JavaScript तभी लोड होता है जब कोई पाठक इसे पहली बार खोलता है। जो पाठक इसे कभी छूते ही नहीं, वे इसका कुछ भी डाउनलोड नहीं करते।

playground: false ही पूरा बंद-स्विच है:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: false,
}

क्रेडेंशियल

प्रामाणीकरण इनपुट में टाइप किए गए क्रेडेंशियल मेमोरी में रहते हैं और रीलोड पर गायब हो जाते हैं। Remember on this device चुनने पर वे localStorage में संचित हो जाते हैं, जिनका दायरा दस्तावेज़ ऑरिजिन तक सीमित होता है — जिस API को कॉल किया जा रहा है, उसके अलावा वे कहीं नहीं भेजे जाते। जो भी टाइप किया जाए, कोड नमूने प्लेसहोल्डर (YOUR_TOKEN इत्यादि) ही दिखाते रहते हैं, जब तक पाठक Include my values in samples को चालू न कर दे।

CORS और प्रॉक्सी

Scalar रेंडरर की तरह ही, अनुरोध सीधे ब्राउज़र से लक्ष्य API तक जाते हैं, इसलिए API को दस्तावेज़ साइट से क्रॉस-ऑरिजिन अनुरोधों की अनुमति देनी चाहिए (Access-Control-Allow-Origin)। जो API ऐसा नहीं कर सकते, उनके लिए playground.proxy सेट करें: एक URL अनुरोधों को आपके द्वारा होस्ट किए गए प्रॉक्सी से होकर भेजता है, और true अंतर्निहित /_api-proxy रूट को सक्षम करता है — जिसके लिए एक सर्वर बिल्ड चाहिए, इसलिए इसे deployment.output: "server" की आवश्यकता होती है:

openapi: {
  enabled: true,
  spec: "./openapi.yaml",
  playground: {
    proxy: true,   // or a URL of your own
  },
}

अंतर्निहित प्रॉक्सी केवल उन्हीं ऑरिजिन तक अनुरोध अग्रेषित करता है जिन्हें आपके स्पेक servers में घोषित करते हैं — रीडायरेक्ट के आर-पार भी — इसलिए किसी सार्वजनिक दस्तावेज़ परिनियोजन को उसके नेटवर्क के अन्य होस्ट की ओर नहीं मोड़ा जा सकता। पैनल में टाइप किया गया Custom base URL एक प्रलेखित सर्वर नहीं होता: प्रॉक्सी सक्षम होने पर, उस तक जाने वाले अनुरोध 403 के साथ अस्वीकार कर दिए जाते हैं।

एकाधिक स्पेक

एक से अधिक स्पेक प्रकाशित करने के लिए sources का उपयोग करें। प्रत्येक स्रोत को अपना अवलोकन रूट, ऑपरेशन पृष्ठ और हेडर टैब मिलता है। प्रत्येक को एक label दें (टैब के लिए और उसका रूट प्राप्त करने के लिए उपयोग किया जाता है), या एक स्पष्ट route सेट करें:

openapi: {
  enabled: true,
  sources: [
    { label: "Public API", spec: "./public.json" },   // → /reference/public-api
    { label: "Admin API", route: "/admin", spec: "./admin.json" },
  ],
}

spec एकल-प्रविष्टि वाले sources का संक्षिप्त रूप है, इसलिए आप sources तभी उपयोग करते हैं जब आपके पास एक से अधिक हों।

प्रति-स्रोत अनुक्रमण

जनरेट किए गए पृष्ठ डिफ़ॉल्ट रूप से खोज, llms.txt और क्रॉलर अनुक्रमण में शामिल होते हैं। कोई द्वितीयक या अतिव्यापी स्पेक अपने पृष्ठों को छिपाए बिना या नेविगेशन से हटाए बिना किसी भी सतह से बाहर निकल सकता है:

openapi: {
  enabled: true,
  sources: [
    { label: "Public API", route: "/api", spec: "./public.json" },
    {
      label: "Platform API",
      route: "/platform",
      spec: "./platform.json",
      includeInSearch: false,
      includeInLlms: false,
      noindex: true,
    },
  ],
}

includeInSearch: false स्रोत के अवलोकन और ऑपरेशनों को साइट खोज से बाहर रखता है।
includeInLlms: false उन्हें दोनों llms.txt फ़ाइलों से बाहर रखता है।
noindex: true क्रॉलर noindex मेटाडेटा जोड़ता है और पृष्ठों को साइटमैप से हटा देता है।

प्रत्येक ऑपरेशन पृष्ठ का मेटा विवरण स्वयं ऑपरेशन का description (या summary) होता है, जिसके बाद एंडपॉइंट का नाम बताने वाला एक जनरेट किया गया वाक्य आता है — “Reference for the GET /pets endpoint in the Petstore API.” — इसलिए संक्षिप्त एक-पंक्ति सारांशों वाला स्पेक भी प्रति पृष्ठ एक विशिष्ट, स्निपेट-लंबाई का विवरण देता है। वह वाक्य अंग्रेज़ी में होता है। जिस साइट का स्पेक गद्य किसी अन्य भाषा में लिखा गया हो, वहाँ स्रोत पर seoDescriptionSuffix: false सेट करके उसे हटा दें और प्रत्येक पृष्ठ का वर्णन केवल लिखे गए गद्य से करें; जिस ऑपरेशन में न description हो और न summary, वह अपने शीर्षक (GET /pets) पर लौट आता है, इसलिए कोई भी पृष्ठ खाली विवरण के साथ प्रकाशित नहीं होता:

openapi: {
  enabled: true,
  sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
}

Scalar रेंडरर के साथ केवल noindex लागू होता है — Scalar द्वारा रेंडर किया गया संदर्भ पहले से ही Blume की खोज और llms.txt के बाहर होता है, इसलिए वहाँ दोनों include* सेटिंग्स के लिए कुछ करने को नहीं बचता।

प्राधिकरण

जो ऑपरेशन सुरक्षा आवश्यकताएँ घोषित करते हैं, वे अपने पैरामीटर के ऊपर एक Authorization अनुभाग रेंडर करते हैं, और जनरेट किए गए कोड नमूने एक प्लेसहोल्डर क्रेडेंशियल भेजते हैं (Authorization: Bearer YOUR_TOKEN, एक API-कुंजी हेडर, या एक क्वेरी कुंजी — जो भी उस योजना की माँग हो)। कॉन्फ़िगर करने के लिए कुछ नहीं है: Blume स्पेक से security पढ़ता है, इसलिए संदर्भ हमेशा उससे मेल खाता है जो API वास्तव में लागू करता है।

OpenAPI का अर्थ-विधान जस का तस लागू होता है:

किसी ऑपरेशन का अपना security दस्तावेज़ के रूट डिफ़ॉल्ट को अधिरोहित करता है; security: [] इसे सार्वजनिक चिह्नित करता है और कोई Authorization अनुभाग रेंडर नहीं करता।
एकाधिक आवश्यकता प्रविष्टियाँ विकल्प होती हैं — “or” समूहों के रूप में रेंडर की जाती हैं; एक प्रविष्टि के भीतर की हर योजना एक साथ आवश्यक होती है। पहला विकल्प कोड नमूनों को आपूर्ति करता है।
एक खाली {} प्रविष्टि का अर्थ है कि उस ऑपरेशन के लिए प्रमाणीकरण वैकल्पिक है, और अनुभाग ऐसा ही बताता है।
OAuth2 स्कोप प्रति योजना सूचीबद्ध किए जाते हैं; components.securitySchemes से योजना के description इनलाइन रेंडर होते हैं।

Scalar रेंडरर

नेटिव रेंडरर डिफ़ॉल्ट है — ऑपरेशन पृष्ठ, खोज एकीकरण और ऊपर बताया गया “Try it” प्लेग्राउंड, ये सब उसी का काम हैं। यदि आप इसके बजाय Scalar का स्वयं-निहित API संदर्भ UI एम्बेड करना चाहते हैं — इसका अपना साइडबार, खोज, थीम और एक ही रूट पर अनुरोध क्लाइंट — तो renderer: "scalar" सेट करें:

openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  theme: "purple",   // a Scalar theme name (Scalar renderer only)
}

Scalar द्वारा रेंडर किया गया संदर्भ अपने स्वयं के रूट पर एक स्वयं-निहित एम्बेड होता है — यह Blume के साइडबार, खोज या llms.txt में नहीं बुनता, और Blume का playground कॉन्फ़िग इस पर लागू नहीं होता। यह Blume के लाइट/डार्क टॉगल का अनुसरण अवश्य करता है: माउंट होते समय एम्बेड पृष्ठ की थीम से बँध जाता है और उसी के साथ बदलता है, इसलिए Scalar का अपना थीम स्विच छिपा दिया जाता है (रंग मोड वापस Scalar को सौंपने के लिए scalar.forceDarkModeState या scalar.darkMode सेट करें)। Scalar अपना स्वयं का अनुरोध क्लाइंट लाता है, जो आपके लक्ष्य API को सीधे ब्राउज़र से कॉल करता है (playground.proxy रूट यहाँ उपलब्ध नहीं है), इसलिए API को दस्तावेज़ साइट से क्रॉस-ऑरिजिन अनुरोधों की अनुमति देनी चाहिए (Access-Control-Allow-Origin)। theme केवल Scalar रेंडरर पर लागू होता है।

Scalar विकल्प पास करना

theme उस एक विकल्प का संक्षिप्त रूप है जिसे अधिकांश लोग चुनते हैं, लेकिन Scalar इससे कहीं अधिक का समर्थन करता है। एक scalar ऑब्जेक्ट किसी भी Scalar कॉन्फ़िगरेशन को सीधे एम्बेडेड संदर्भ तक अग्रेषित करता है — Blume कुंजियों पर रोक नहीं लगाता, इसलिए जो कुछ भी Scalar स्वीकार करता है वह प्रवाहित हो जाता है:

openapi: {
  enabled: true,
  renderer: "scalar",
  spec: "./openapi.yaml",
  scalar: {
    localization: { locale: "es" },   // translate Scalar's own UI
    agent: { disabled: true },         // disable the Scalar Agent
    hideTestRequestButton: true,
    orderSchemaPropertiesBy: "preserve",
  },
}

Blume का अपना i18n दस्तावेज़ क्रोम का अनुवाद करता है, लेकिन Scalar की एक अलग स्थानीयकरण प्रणाली है — एम्बेडेड संदर्भ का भी अनुवाद करने के लिए scalar.localization.locale सेट करें। scalar ऑब्जेक्ट के विकल्प Blume के व्युत्पन्न कॉन्फ़िग पर भारी पड़ते हैं, इसलिए यहाँ सेट की गई कोई भी चीज़ (theme, customCss, या स्पेक content/url सहित) Blume के डिफ़ॉल्ट को अधिरोहित कर देती है। यही scalar ब्लॉक asyncapi संदर्भ पर भी काम करता है।

AsyncAPI

इवेंट-चालित API समान आकार वाले एक सहोदर asyncapi ब्लॉक का उपयोग करते हैं — और उसी नेटिव रेंडरर का भी। प्रत्येक send/receive ऑपरेशन एक वास्तविक पृष्ठ बन जाता है, जिसमें संदेश पेलोड और हेडर स्कीमा तालिकाएँ, चैनल पैरामीटर, प्रोटोकॉल बाइंडिंग, स्पेक के securitySchemes से व्युत्पन्न एक Authorization अनुभाग (सर्वर-स्तर और ऑपरेशन-स्तर, विकल्प “or” समूहों के रूप में), और एक “Try it” संदेश संयोजक होता है। केवल डिफ़ॉल्ट रूट अलग है (/events):

asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
}

AsyncAPI 2.x स्पेक आधिकारिक AsyncAPI कनवर्टर से स्वचालित रूप से 3.x में सामान्यीकृत हो जाते हैं, इसलिए publish/subscribe चैनल स्थिर URL वाले send/receive ऑपरेशन पृष्ठों पर मैप होते हैं — बाद में स्पेक फ़ाइल को स्वयं कनवर्टर से अपग्रेड करने पर कुछ भी नहीं हिलता। ऑपरेशन टैग के अनुसार समूहीकृत होते हैं; बिना टैग वाले ऑपरेशन अपने चैनल पते के अंतर्गत समूहीकृत होते हैं।

कोड नमूने प्रोटोकॉल-सजग होते हैं, जो ऑपरेशन की बाइंडिंग (या उसके सर्वरों के प्रोटोकॉल) के आधार पर तय होते हैं: WebSockets के लिए wscat और एक ब्राउज़र WebSocket स्निपेट, Kafka के लिए kcat, MQTT के लिए mosquitto_pub/mosquitto_sub। codeSamples उस सेट को उसी तरह फ़िल्टर करता है जिस तरह वह openapi ब्लॉक पर भाषाएँ चुनता है; जिस प्रोटोकॉल के लिए कोई समर्थित टूल नहीं है, वह किसी गढ़े हुए क्लाइंट के बजाय केवल संदेश पेलोड उदाहरण रेंडर करता है।

ऊपर प्रलेखित सब कुछ जस का तस लागू रहता है, playground सहित: route, label/route के साथ sources, expandSchemas, प्रति-स्रोत अनुक्रमण फ़्लैग (seoDescriptionSuffix भी — जनरेट किया गया वाक्य एंडपॉइंट के बजाय चैनल और क्रिया का नाम बताता है), और ऑपरेशन सारांश व टैग के आधार पर खोज अनुक्रमण।

renderer: "scalar" सेट करने से आप एम्बेडेड Scalar SPA में वापस लौट जाते हैं, जहाँ — OpenAPI की तरह — केवल noindex लागू होता है। Scalar का अपना कोई AsyncAPI प्लेग्राउंड नहीं है; इसका एम्बेड दस्तावेज़ का प्रकार स्वयं पहचान लेता है और चैनल, ऑपरेशन, संदेश तथा एक Models अनुभाग रेंडर करता है, इसलिए इस अदला-बदली में संयोजक हाथ से निकल जाता है।

इवेंट्स के लिए “Try it”

नेटिव रूप से रेंडर किए गए ऑपरेशन पृष्ठ यहाँ भी एक Try it पैनल के साथ आते हैं, उन्हीं शर्तों पर जिन पर OpenAPI पैनल आता है: सर्वर-रेंडर होकर सिकुड़ी अवस्था में, और इसका JavaScript तभी लोड होता है जब कोई पाठक इसे पहली बार खोलता है।

प्रोटोकॉल जो भी हो, पैनल एक पेलोड संपादक के साथ खुलता है जो संदेश के examples से पहले से भरा होता है — या, जब संदेश कोई घोषित नहीं करता, तो पेलोड स्कीमा से लिए गए एक नमूना मान से — और टाइप करते समय संदेश पेलोड स्कीमा के विरुद्ध सत्यापित होता रहता है। उसके नीचे प्रत्येक चैनल पैरामीटर के लिए एक इनपुट और चैनल के servers से भरा एक सर्वर चयनकर्ता होता है, साथ ही किसी अन्य URL के लिए एक मुक्त-पाठ फ़ील्ड। प्रोटोकॉल-सजग कोड नमूने फ़ॉर्म के साथ ठीक वैसे ही कदम मिलाकर चलते हैं जैसे किसी HTTP ऑपरेशन पर curl, js और python चलते हैं: चैनल पता टेम्पलेट आपके टाइप किए गए पैरामीटर मानों से भर दिया जाता है, इसलिए कॉपी किया गया wscat, WebSocket, kcat या mosquitto_pub स्निपेट वही दर्शाता है जो फ़ॉर्म कहता है।

लाइव कनेक्ट केवल WebSocket के लिए है। किसी ws या wss बाइंडिंग पर पैनल हल किए गए चैनल URL से जुड़ता है, कनेक्शन की स्थिति दिखाता है, और हर फ़्रेम को टाइमस्टैम्प के साथ लॉग करता है। AsyncAPI 3 किसी क्रिया को API के पक्ष से बताता है, और पैनल उसी का अनुसरण करता है: एक receive ऑपरेशन वह है जिसे API आपसे प्राप्त करता है, इसलिए उसे एक Send बटन मिलता है जो संयोजित पेलोड प्रकाशित करता है; एक send ऑपरेशन केवल आपकी ओर संदेश प्रवाहित करता है, इसलिए वह जुड़ता है और लॉग करता है। कोई पुनः-कनेक्ट तर्क नहीं है — एक बार सॉकेट बंद हो जाने पर, जब तक आप दोबारा न जुड़ें, वह बंद ही रहता है। Kafka, MQTT, AMQP और हर दूसरे प्रोटोकॉल को संयोजक तथा कॉपी करने योग्य CLI नमूने मिलते हैं, और पैनल पृष्ठ पर यही बात कहता है: Blume किसी ब्राउज़र टैब से ब्रोकर कनेक्टिविटी का नाटक नहीं करता।

asyncapi.playground, openapi.playground का दर्पण है — नेटिव रेंडरर के साथ डिफ़ॉल्ट रूप से चालू, और false ही पूरा बंद-स्विच है:

asyncapi: {
  enabled: true,
  spec: "./asyncapi.yaml",
  playground: false,
}

इवेंट संयोजक कोई ब्रोकर क्रेडेंशियल एकत्र नहीं करता। प्रत्येक ऑपरेशन पृष्ठ का Authorization अनुभाग प्रलेखित करता है कि ब्रोकर क्या अपेक्षा करता है, और एक WebSocket कनेक्ट केवल वही ले जाता है जो पहले से URL में मौजूद है। इवेंट ऑपरेशनों के लिए कुछ भी संचित नहीं किया जाता।