---
title: GraphQL
description: >-
  एक GraphQL स्कीमा जोड़ें और नेटिव API संदर्भ पाएँ। इसमें हर ऑपरेशन और हर टाइप का एक वास्तविक पेज बनता है, जो आपके साइडबार और खोज में दिखाई देता है।
---

Blume को किसी GraphQL स्कीमा की ओर इंगित करें, और यह एक नेटिव API संदर्भ जनरेट करता है। इसमें प्रत्येक **रूट फ़ील्ड का एक वास्तविक पेज** बनता है, जिसमें क्वेरी, म्यूटेशन और सब्सक्रिप्शन शामिल हैं। साथ ही प्रत्येक **नामित टाइप का एक पेज** बनता है (ऑब्जेक्ट, इनपुट ऑब्जेक्ट, एनम, इंटरफ़ेस, यूनियन और कस्टम स्केलर)। हर पेज आर्ग्युमेंट, डिफ़ॉल्ट मान, डेप्रिकेशन और उपयोग बैकलिंक दिखाता है। इनके साथ एक जनरेट किया गया उदाहरण ऑपरेशन, कोड सैंपल और एक इंटरैक्टिव [Try it](#try-it-playground) पैनल भी होता है। प्रत्येक पेज एक वास्तविक Blume पेज होता है। इसलिए उसका अपना URL होता है, वह **साइट खोज** और `llms.txt` में दिखाई देता है, और उसे एक Open Graph इमेज मिलती है। यह ठीक वैसा ही है जैसा किसी हाथ से लिखे दस्तावेज़ के साथ होता है।

यह संदर्भ `blume/reference` का `graphql()` एडैप्टर है। इसे `reference` के अंतर्गत सूचीबद्ध किया जाता है, और वहाँ यह किसी भी [OpenAPI](/docs/references/openapi) या [AsyncAPI](/docs/references/asyncapi) एडैप्टर के साथ रह सकता है:

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

export default defineConfig({
  reference: [
    graphql({
      spec: "./schema.graphql",
      endpoint: "https://api.example.com/graphql",
    }),
  ],
});
```

इससे संदर्भ `/graphql` पर माउंट हो जाता है, जो एक अवलोकन पेज है। रूट फ़ील्ड `/graphql/queries/<field>`, `/graphql/mutations/<field>` और `/graphql/subscriptions/<field>` पर होते हैं। टाइप अपने प्रकार के अनुसार समूहित होकर `/graphql/objects/<type>`, `/graphql/enums/<type>` आदि पर होते हैं।

`spec` या तो आपके प्रोजेक्ट की किसी लोकल फ़ाइल का पाथ होता है या कोई `http(s)` URL। यह दो फ़ॉर्मैट स्वीकार करता है:

- **SDL टेक्स्ट**: टाइप परिभाषाओं वाली एक `.graphql` फ़ाइल।
- **इंट्रोस्पेक्शन परिणाम**: मानक इंट्रोस्पेक्शन क्वेरी चलाने से मिलने वाला JSON। यह कच्चे `{ "__schema": … }` रूप में हो सकता है या पूर्ण `{ "data": { "__schema": … } }` रिस्पॉन्स एनवेलप के रूप में।

`endpoint` लाइव GraphQL API का URL है। OpenAPI दस्तावेज़ के विपरीत, स्कीमा में किसी सर्वर का नाम नहीं होता। इसलिए Try it पैनल और जनरेट किए गए कोड सैंपल इसी endpoint पर अनुरोध भेजते हैं। यदि आप इसे छोड़ देते हैं, तो सैंपल एक प्लेसहोल्डर URL के साथ रेंडर होते हैं, जिसे पाठकों को स्वयं बदलना होता है।

संदर्भ अपने आप कोई हेडर टैब नहीं जोड़ता। इसे दिखाने के लिए किसी [नेविगेशन टैब](/docs/content/navigation#tabs) को इसके रूट की ओर इंगित करें। इससे साइडबार भी केवल इसी संदर्भ तक सीमित हो जाता है:

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

## जनरेट किए गए उदाहरण [#generated-examples]

हर ऑपरेशन पेज में एक पूर्ण और मान्य उदाहरण ऑपरेशन होता है। इसमें प्रत्येक आर्ग्युमेंट के लिए एक वेरिएबल होता है, जिसका टाइप स्कीमा से लिया जाता है। रिटर्न टाइप पर एक सीमित गहराई वाला सिलेक्शन सेट भी होता है। साथ ही, इनसे मेल खाते उदाहरण वेरिएबल और एक उदाहरण रिस्पॉन्स भी होता है, जो उसी सिलेक्शन के अनुरूप होता है। कोड सैंपल प्रत्येक कॉन्फ़िगर की गई भाषा में सटीक HTTP अनुरोध दिखाते हैं, यानी `{ query, variables }` का एक JSON `POST`:

```ts blume.config.ts lineNumbers
reference: [
  graphql({
    spec: "./schema.graphql",
    codeSamples: ["curl", "js"],   // built in: curl, js, python
  }),
],
```

## टाइप पेज [#type-pages]

नामित टाइप्स के अपने पेज बनते हैं, जिनसे सीधे लिंक किया जा सकता है। ये साइडबार में प्रकार के अनुसार समूहित होते हैं। इन पेजों में ये चीज़ें होती हैं:

फ़ील्ड और इनपुट फ़ील्ड (उनके टाइप के लिंक के साथ), एनम मान, यूनियन सदस्य और इंटरफ़ेस इम्प्लीमेंटेशन। एक **Used by** सेक्शन भी होता है, जो उन ऑपरेशनों को सूचीबद्ध करता है जो उस टाइप को लौटाते या स्वीकार करते हैं। यह उन अन्य टाइप्स को भी सूचीबद्ध करता है जो उस टाइप का संदर्भ देते हैं। स्पेक द्वारा परिभाषित स्केलर (`String`, `Int`, …) के पेज नहीं बनते। कस्टम स्केलर के पेज बनते हैं, और उनमें उनका `specifiedBy` URL भी शामिल होता है।

## एकाधिक स्कीमा [#multiple-schemas]

`sources` की प्रत्येक एंट्री एक स्कीमा को उसके अपने रूट पर रेंडर करती है। किसी स्रोत में दिया गया `endpoint` एडैप्टर के `endpoint` को ओवरराइड करता है:

```ts blume.config.ts lineNumbers
reference: [
  graphql({
    endpoint: "https://api.example.com/graphql",
    sources: [
      { label: "Public API", spec: "./schema.graphql" },
      {
        label: "Admin API",
        route: "/graphql-admin",
        spec: "./admin.graphql",
        endpoint: "https://admin.example.com/graphql",
      },
    ],
  }),
],
```

`spec` केवल एक एंट्री वाले `sources` का संक्षिप्त रूप है। जिन स्कीमा को अलग डिस्प्ले विकल्प चाहिए, उन्हें अलग `graphql()` एडैप्टर में रखें। ऐसे हर एडैप्टर का अपना `route` होता है। प्रत्येक स्रोत `openapi()` वाले ही [प्रति-स्रोत नियंत्रण](/docs/references/openapi#per-source-indexing) स्वीकार करता है: `includeInSearch`, `includeInLlms`, `noindex` और `seoDescriptionSuffix`। यहाँ जनरेट किए गए वाक्य में क्वेरी, म्यूटेशन या टाइप का नाम आता है, जैसे "Reference for the `pets` query in the GraphQL API."।

## Try it प्लेग्राउंड [#try-it-playground]

क्वेरी और म्यूटेशन पेज एक इंटरैक्टिव पैनल दिखाते हैं। इसमें आप अनुरोध बॉडी (क्वेरी और वेरिएबल) संपादित कर सकते हैं। आप इसे अपने endpoint या किसी कस्टम URL की ओर इंगित करके अनुरोध भेज सकते हैं। कोड सैंपल साथ-साथ अपडेट होते रहते हैं, इसलिए आप जो कॉपी करते हैं वह बाइट-दर-बाइट वही होता है जो भेजा गया था। इसे `playground: false` से अक्षम करें।

सब्सक्रिप्शन पेजों पर यह पैनल नहीं होता। उन पर जनरेट किया गया ऑपरेशन और एक उदाहरण इवेंट दिखाया जाता है। इसका कारण यह है कि सब्सक्रिप्शन एक स्टेटफ़ुल ट्रांसपोर्ट (WebSocket या SSE) पर चलते हैं, और प्लेग्राउंड का एकल HTTP `POST` उनके साथ काम नहीं कर सकता।

हो सकता है कि आपका GraphQL API दस्तावेज़ साइट से क्रॉस-ओरिजिन अनुरोधों की अनुमति न देता हो। ऐसे में अनुरोधों को किसी CORS प्रॉक्सी के माध्यम से भेजें। यह आपका अपना कोई URL हो सकता है। या फिर बिल्ट-इन `/_api-proxy` endpoint के लिए `true` सेट करें। इसके लिए [सर्वर आउटपुट](/docs/deployment#server-rendering) आवश्यक है, यानी एक होस्ट एडैप्टर, जैसे `blume/deploy` से `deployment: vercel()`।

बिल्ट-इन प्रॉक्सी केवल उन्हीं ओरिजिन पर अनुरोध भेजता है जो आपके दस्तावेज़ित स्पेक में घोषित हैं। इनमें प्रत्येक कॉन्फ़िगर किया गया GraphQL `endpoint` शामिल है, और किसी दस्तावेज़ित [OpenAPI स्पेक](/docs/references/openapi) का हर निरपेक्ष (absolute) `servers[].url` भी। इससे किसी सार्वजनिक दस्तावेज़ डिप्लॉयमेंट से अन्य होस्ट पर अनुरोध नहीं भेजे जा सकते। इसी कारण कार्यशील प्रॉक्सी के लिए `endpoint` आवश्यक है। इसके बिना प्रॉक्सी के पास इस संदर्भ के लिए कोई अनुमत ओरिजिन नहीं होता, और वह हर अनुरोध को अस्वीकार कर देता है। बिल्ड इस बारे में चेतावनी देता है। बॉडी की सीमा और रिस्पॉन्स हेडर वही लागू होते हैं जो [OpenAPI प्रॉक्सी](/docs/references/openapi#try-it-playground) पर होते हैं।

```ts blume.config.ts lineNumbers
reference: [
  graphql({
    spec: "./schema.graphql",
    endpoint: "https://api.example.com/graphql",
    playground: { proxy: true },
  }),
],
```

GraphQL के लिए Scalar का कोई विकल्प नहीं है। [`scalar()`](/docs/references/scalar) एम्बेड केवल OpenAPI और AsyncAPI दस्तावेज़ पढ़ता है। इसलिए GraphQL संदर्भ हमेशा नेटिव रूप से रेंडर होता है।