GraphQL

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

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

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

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 फ़ाइल। फ़ाइल जिन डायरेक्टिव का उपयोग उन्हें घोषित किए बिना करती है, जैसे Apollo Federation का @key या AppSync का @aws_*, उन्हें अनदेखा कर दिया जाता है।
• इंट्रोस्पेक्शन परिणाम: मानक इंट्रोस्पेक्शन क्वेरी चलाने से मिलने वाला JSON। यह कच्चे { "__schema": … } रूप में हो सकता है या पूर्ण { "data": { "__schema": … } } रिस्पॉन्स एनवेलप के रूप में।

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

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

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

अपने स्कीमा से GraphQL दस्तावेज़ जनरेट करें गाइड आपको स्कीमा से लेकर डिप्लॉय की गई साइट तक की पूरी प्रक्रिया चरण-दर-चरण समझाती है। इसमें एक Try it पैनल भी शामिल है, जो किसी सैंडबॉक्स पर क्वेरी भेजता है।

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

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

reference: [
  graphql({
    spec: "./schema.graphql",
    codeSamples: ["curl", "js"],   // any language openapi() offers
  }),
],

जिस id के लिए Blume कोई सैंपल जनरेट नहीं करता, उसे छोड़ दिया जाता है। साथ ही एक BLUME_GRAPHQL_UNKNOWN_CODE_SAMPLE चेतावनी दी जाती है, जिसमें वे id सूचीबद्ध होती हैं जिनके लिए Blume सैंपल जनरेट करता है।

टाइप पेज

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

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

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

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() वाले ही प्रति-स्रोत नियंत्रण स्वीकार करता है: includeInSearch, includeInLlms, noindex और seoDescriptionSuffix। यहाँ जनरेट किए गए वाक्य में क्वेरी, म्यूटेशन या टाइप का नाम आता है, जैसे “Reference for the pets query in the GraphQL API.”।

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

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

स्कीमा यह नहीं बताता कि उसका API प्रमाणीकरण कैसे करता है। इसलिए जब तक आप auth सेट नहीं करते, तब तक पैनल कोई क्रेडेंशियल नहीं भेजता। auth वही संरचना लेता है जो हाथ से लिखे endpoint पेजों के लिए api.auth की होती है: method का मान bearer, basic, key (हेडर में भेजी जाने वाली API कुंजी) या none होता है, और name वह हेडर है जिसमें API कुंजी भेजी जाती है (डिफ़ॉल्ट रूप से x-api-key)। इसके बाद हर ऑपरेशन पेज में एक Authorization सेक्शन जुड़ जाता है। पैनल में एक क्रेडेंशियल फ़ील्ड आ जाता है, जो OpenAPI वाले फ़ील्ड की तरह काम करता है, और कोड सैंपल में एक प्लेसहोल्डर क्रेडेंशियल दिखाई देता है। किसी स्रोत में दिया गया auth एडैप्टर के auth को ओवरराइड करता है:

reference: [
  graphql({
    spec: "./schema.graphql",
    endpoint: "https://api.example.com/graphql",
    auth: { method: "bearer" },
  }),
],

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

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

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