GraphQL

एक GraphQL स्कीमा जोड़ें और एक नेटिव API संदर्भ प्राप्त करें — प्रति ऑपरेशन और प्रति टाइप एक वास्तविक पेज, आपके साइडबार और खोज में।

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

graphql: {
  enabled: true,
  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 पैनल और जनरेट किए गए कोड नमूने उपयोग करते हैं। इसे छोड़ दें और नमूने एक प्लेसहोल्डर URL के साथ रेंडर होंगे जिसे पाठक बदल सकते हैं।

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

navigation: {
  tabs: [{ label: "GraphQL", path: "/graphql" }],
}

जनरेट किए गए उदाहरण

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

graphql: {
  enabled: true,
  spec: "./schema.graphql",
  codeSamples: ["curl", "js"],   // built in: curl, js, python
}

टाइप पेज

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

एकाधिक स्कीमा

sources की प्रत्येक प्रविष्टि एक स्कीमा को उसके अपने रूट पर रेंडर करती है। प्रति-स्रोत endpoint ब्लॉक-स्तरीय एंडपॉइंट को ओवरराइड करता है:

graphql: {
  enabled: true,
  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",
    },
  ],
}

प्रत्येक स्रोत वही प्रति-स्रोत नियंत्रण लेता है जो OpenAPI ब्लॉक लेता है: includeInSearch, includeInLlms, noindex और seoDescriptionSuffix (यहाँ जनरेट किया गया वाक्य क्वेरी, म्यूटेशन या टाइप का नाम लेता है — “Reference for the pets query in the GraphQL API.”)।

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

क्वेरी और म्यूटेशन पेज एक इंटरैक्टिव पैनल रेंडर करते हैं: अनुरोध बॉडी (क्वेरी और वेरिएबल) संपादित करें, इसे अपने एंडपॉइंट या किसी कस्टम URL की ओर इंगित करें, और भेजें — कोड नमूने लाइव अपडेट होते हैं ताकि आप जो कॉपी करें वह बाइट-दर-बाइट वही हो जो भेजा गया था। इसे playground: false से अक्षम करें। सब्सक्रिप्शन पेज इसके बजाय जनरेट किया गया ऑपरेशन और एक उदाहरण इवेंट दिखाते हैं: सब्सक्रिप्शन एक स्टेटफ़ुल ट्रांसपोर्ट (WebSocket या SSE) पर चलते हैं, जिसे प्लेग्राउंड का एकल HTTP POST नहीं समझ सकता।

यदि आपका GraphQL API डॉक्स साइट से क्रॉस-ऑरिजिन अनुरोधों की अनुमति नहीं देता, तो सेंड को एक CORS प्रॉक्सी के माध्यम से रूट करें — अपना कोई URL, या अंतर्निर्मित /_api-proxy एंडपॉइंट के लिए true (जिसके लिए deployment.output: "server" आवश्यक है)। अंतर्निर्मित प्रॉक्सी केवल उन्हीं ऑरिजिन्स पर अग्रेषित करता है जिन्हें आपकी प्रलेखित स्पेक्स घोषित करती हैं — प्रत्येक कॉन्फ़िगर किया गया GraphQL endpoint, साथ ही किसी प्रलेखित OpenAPI स्पेक से कोई भी निरपेक्ष servers[].url — ताकि एक सार्वजनिक डॉक्स डिप्लॉयमेंट को अन्य होस्ट्स की ओर लक्षित न किया जा सके। इससे कार्यशील प्रॉक्सी के लिए endpoint आवश्यक हो जाता है: इसके बिना, प्रॉक्सी के पास इस संदर्भ के लिए अनुमति देने योग्य कोई ऑरिजिन नहीं होता और वह हर सेंड को अस्वीकार कर देता है (बिल्ड इस बारे में चेतावनी देता है)।

graphql: {
  enabled: true,
  spec: "./schema.graphql",
  endpoint: "https://api.example.com/graphql",
  playground: { proxy: true },
}