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

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

```ts blume.config.ts lineNumbers
import { defineConfig } from "blume";
import { asyncapi } from "blume/reference";

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

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

```ts blume.config.ts
navigation: {
  tabs: [{ label: "Events", path: "/events" }],
}
```

## Spec संस्करण [#spec-versions]

आधिकारिक 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 को किसी अतिरिक्त चीज़ की आवश्यकता नहीं होती। ऑपरेशंस टैग के अनुसार समूहित होते हैं। बिना टैग वाले ऑपरेशंस अपने चैनल एड्रेस के अंतर्गत समूहित होते हैं।

## कोड सैंपल [#code-samples]

कोड सैंपल **प्रोटोकॉल-अवेयर** होते हैं। वे ऑपरेशन की बाइंडिंग या उसके सर्वरों के प्रोटोकॉल के आधार पर तय होते हैं:

- WebSockets के लिए `wscat` और एक ब्राउज़र `WebSocket` स्निपेट
- Kafka के लिए `kcat`
- MQTT के लिए `mosquitto_pub`/`mosquitto_sub`

`codeSamples` इस सेट को फ़िल्टर करता है, ठीक उसी तरह जैसे यह `openapi()` में भाषाएँ चुनता है। यदि किसी प्रोटोकॉल के लिए कोई समर्थित टूल नहीं है, तो केवल मैसेज पेलोड का उदाहरण रेंडर होता है। ऐसे में कोई मनगढ़ंत क्लाइंट नहीं दिखाया जाता।

## साझा विकल्प [#shared-options]

[OpenAPI](/docs/references/openapi) के लिए प्रलेखित सभी विकल्प यहाँ भी लागू होते हैं, जिनमें [`playground`](#try-it-for-events) भी शामिल है:

- [`route`](/docs/references/openapi#route)
- `label`/`route` के साथ [`sources`](/docs/references/openapi#multiple-specs)
- `expandSchemas`
- [प्रति-सोर्स इंडेक्सिंग](/docs/references/openapi#per-source-indexing) फ़्लैग्स, जिनमें `seoDescriptionSuffix` भी शामिल है। इसमें जनरेट किया गया वाक्य एंडपॉइंट के बजाय चैनल और एक्शन का नाम बताता है।
- ऑपरेशन सारांश और टैग के आधार पर सर्च इंडेक्सिंग

## इसके बजाय Scalar एम्बेड करना [#embedding-scalar-instead]

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

## इवेंट्स के लिए Try it [#try-it-for-events]

नेटिव रूप से रेंडर किए गए ऑपरेशन पेजों में यहाँ भी एक **Try it** पैनल होता है। यह [OpenAPI पैनल](/docs/references/openapi#try-it-playground) की तरह ही काम करता है। सर्वर इसे बंद (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` सेट करें:

```ts blume.config.ts lineNumbers
reference: [asyncapi({ spec: "./asyncapi.yaml", playground: false })],
```

:::note
`playground.proxy` इवेंट ऑपरेशंस पर लागू नहीं होता। यह केवल HTTP अनुरोधों को फ़ॉरवर्ड करता है। WebSocket कनेक्शन ब्राउज़र से सीधे URL में दिए गए सर्वर तक जाता है। इसलिए बीच में प्रॉक्सी की कोई भूमिका नहीं होती।
:::

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