AsyncAPI

एक AsyncAPI spec जोड़ें और एक नेटिव इवेंट रेफ़रेंस पाएँ — हर send और receive ऑपरेशन के लिए एक वास्तविक पेज, आपके साइडबार और सर्च में।

इवेंट-ड्रिवन APIs, blume/reference के asyncapi() एडैप्टर का उपयोग करते हैं। इसे reference के अंतर्गत किसी भी OpenAPI या GraphQL एडैप्टर के साथ सूचीबद्ध किया जाता है। यह openapi() जैसे ही विकल्प लेता है और उसी नेटिव रेंडरर से रेंडर होता है। प्रत्येक send/receive ऑपरेशन एक वास्तविक पेज बन जाता है। इस पेज में मैसेज पेलोड और हेडर स्कीमा टेबल, चैनल पैरामीटर, प्रोटोकॉल बाइंडिंग और spec के securitySchemes से बना एक Authorization सेक्शन होता है। इस सेक्शन में सर्वर-स्तर और ऑपरेशन-स्तर दोनों शामिल होते हैं, और विकल्प “or” समूहों के रूप में दिखाए जाते हैं। जब किसी चैनल के सर्वर अलग-अलग होते हैं, तो यह सेक्शन यह भी बताता है कि प्रत्येक स्कीम किन सर्वरों पर लागू होती है। पेज पर एक Try it मैसेज कंपोज़र भी होता है। चूँकि प्रत्येक ऑपरेशन एक वास्तविक Blume पेज है, इसलिए उसे अपना अलग URL मिलता है, वह साइट सर्च और llms.txt में दिखाई देता है, और उसे एक Open Graph इमेज मिलती है — बिल्कुल किसी हाथ से लिखे गए डॉक की तरह।

import { defineConfig } from "blume";
import { asyncapi } from "blume/reference";

export default defineConfig({
  reference: [asyncapi({ spec: "./asyncapi.yaml" })],
});

इससे रेफ़रेंस /events पर माउंट हो जाता है, जो एक ओवरव्यू पेज है। प्रत्येक ऑपरेशन इसके नीचे अपने अलग पेज पर होता है। spec या तो एक http(s) URL होता है या आपके प्रोजेक्ट में किसी लोकल JSON या YAML फ़ाइल का पाथ। हर रेफ़रेंस की तरह, यह अपने आप कोई हेडर टैब नहीं जोड़ता। इसे दिखाने और ऑपरेशंस साइडबार को इसी रेफ़रेंस तक सीमित करने के लिए किसी नेविगेशन टैब को इसके रूट की ओर इंगित करें:

navigation: {
  tabs: [{ label: "Events", path: "/events" }],
}

AsyncAPI के साथ Kafka इवेंट्स को प्रलेखित करें में Kafka टॉपिक्स के लिए इसकी पूरी प्रक्रिया समझाई गई है। वहाँ रेफ़रेंस के साथ-साथ प्रोड्यूसर और कंज़्यूमर कोड भी दिया गया है।

Spec संस्करण

आधिकारिक AsyncAPI कन्वर्टर 2.x specs को स्वचालित रूप से 3.x में नॉर्मलाइज़ कर देता है। इसलिए publish/subscribe चैनल स्थिर URLs वाले send/receive ऑपरेशन पेजों पर मैप होते हैं। यदि आप बाद में कन्वर्टर से spec फ़ाइल को ही अपग्रेड करते हैं, तब भी कोई पेज अपनी जगह से नहीं हटता। कन्वर्टर एक वैकल्पिक peer dependency है। इसलिए जिस साइट में 1.x या 2.x spec है, उसे इसे इंस्टॉल करना होगा (npm install @asyncapi/converter)। इसके बिना बिल्ड विफल हो जाता है और यही इंस्टॉल कमांड दिखाता है। 3.x spec को किसी अतिरिक्त चीज़ की आवश्यकता नहीं होती। ऑपरेशंस टैग के अनुसार समूहित होते हैं। बिना टैग वाले ऑपरेशंस अपने चैनल एड्रेस के अंतर्गत समूहित होते हैं।

कोड सैंपल

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

kcat सैंपल Kafka बाइंडिंग को भी पढ़ता है। चैनल बाइंडिंग का topic, टॉपिक नाम के रूप में चैनल एड्रेस की जगह ले लेता है। मैसेज बाइंडिंग का key मैसेज की key तय करता है: सैंपल -K '|' के साथ key|payload लाइनें प्रोड्यूस करता है, और उसी फ़्लैग के साथ कंज़्यूम करता है, ताकि प्रत्येक key अपने मैसेज से पहले प्रिंट हो। key का मान key स्कीमा से उसी तरह लिया जाता है जैसे पेलोड का मान पेलोड स्कीमा से लिया जाता है, इसलिए स्कीमा में एक examples एंट्री जोड़ें। जब सर्वर कोई SASL स्कीम (plain, scramSha256, scramSha512 या gssapi) घोषित करता है, तो सैंपल librdkafka के लिए आवश्यक -X सेटिंग्स जोड़ देता है, और यूज़रनेम व पासवर्ड $KAFKA_USERNAME और $KAFKA_PASSWORD से पढ़ता है। kafka-secure सर्वर होने पर TLS भी जोड़ा जाता है।

साझा विकल्प

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

इसके बजाय Scalar एम्बेड करना

asyncapi() हमेशा Blume के अपने पेज रेंडर करता है। इसके बजाय Scalar का UI एम्बेड करने के लिए, एक scalar() एडैप्टर सूचीबद्ध करें और उसे AsyncAPI डॉक्यूमेंट की ओर इंगित करें। इसका एम्बेड डॉक्यूमेंट का प्रकार पहचान लेता है। फिर यह चैनल, ऑपरेशंस, मैसेज और एक Models सेक्शन रेंडर करता है। Scalar का अपना कोई AsyncAPI प्लेग्राउंड नहीं है, इसलिए इस बदलाव से आपको कंपोज़र नहीं मिलता। साथ ही, प्रति-सोर्स नियंत्रणों में से केवल noindex ही इस पर लागू होता है।

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

नेटिव रूप से रेंडर किए गए ऑपरेशन पेजों में यहाँ भी एक Try it पैनल होता है। यह OpenAPI पैनल की तरह ही काम करता है। सर्वर इसे बंद (collapsed) अवस्था में रेंडर करता है। इसका 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 सेट करें:

reference: [asyncapi({ spec: "./asyncapi.yaml", playground: false })],

इवेंट कंपोज़र कोई ब्रोकर क्रेडेंशियल नहीं लेता। प्रत्येक ऑपरेशन पेज का Authorization सेक्शन बताता है कि ब्रोकर को क्या चाहिए। WebSocket कनेक्शन केवल वही जानकारी भेजता है जो पहले से URL में है। इवेंट ऑपरेशंस के लिए कोई भी डेटा सहेजा नहीं जाता।