OpenAPI

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

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

प्रत्येक संदर्भ एक एडैप्टर है जिसे blume/reference से इम्पोर्ट किया जाता है और reference के अंतर्गत सूचीबद्ध किया जाता है: OpenAPI दस्तावेज़ के लिए openapi(), AsyncAPI दस्तावेज़ के लिए asyncapi(), और GraphQL स्कीमा के लिए graphql()। प्रत्येक एडैप्टर अपने स्पेक स्रोत, अपना माउंट रूट और अपने डिस्प्ले विकल्प स्वयं सँभालता है, इसलिए सूची में आप प्रत्येक प्रकार के जितने चाहें उतने एडैप्टर रख सकते हैं। नीचे दिया गया कॉन्फ़िग उदाहरण के तौर पर Blume को सार्वजनिक Petstore स्पेक की ओर इंगित करता है।

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

export default defineConfig({
  reference: [
    openapi({ spec: "https://petstore3.swagger.io/api/v3/openapi.json" }),
  ],
});

यह संदर्भ को /reference (एक अवलोकन पेज) पर माउंट करता है, और प्रत्येक ऑपरेशन /reference/<tag>/<operation> पर होता है। spec या तो एक http(s) URL होता है या आपके प्रोजेक्ट में किसी स्थानीय फ़ाइल का पाथ। Blume इसे Scalar के OpenAPI पार्सर से पार्स करता है — Swagger 2.0 और OpenAPI 3.0 स्पेक स्वचालित रूप से 3.1 में अपग्रेड हो जाते हैं, और 3.1 तथा 3.2 स्पेक ठीक वैसे ही पढ़े जाते हैं जैसे वे लिखे गए हैं। एडैप्टर संदर्भ का केवल एक सादा विवरण है, पार्स किया हुआ स्पेक नहीं। इसलिए Blume इसे पहले ही सत्यापित कर सकता है और जनरेट की गई साइट में इनलाइन कर सकता है। यदि आप reference को छोड़ देते हैं (या खाली रखते हैं), तो कोई भी संदर्भ रेंडर नहीं होता। क्या आप इसके बजाय किसी इवेंट-ड्रिवन या GraphQL API का दस्तावेज़ीकरण कर रहे हैं? AsyncAPI और GraphQL देखें।

अपने फ़्रेमवर्क द्वारा जनरेट किए गए स्पेक से डिप्लॉय किए गए संदर्भ तक पहुँचने के लिए FastAPI, Django REST Framework, NestJS, Spring Boot, ASP.NET Core, Laravel, Rails, Hono, Fastify, Elysia या oRPC की गाइड का पालन करें। यदि आप API को TypeSpec में परिभाषित करते हैं, तो इसे TypeSpec परिभाषा से प्रकाशित करें। OpenAPI स्पेक से API दस्तावेज़ जनरेट करें गाइड किसी भी स्पेक फ़ाइल से शुरुआत करती है।

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

navigation: {
  tabs: [{ label: "API", path: "/reference" }],
}

साइडबार के टैग समूह और अवलोकन पेज के अनुभाग एक ही क्रम का पालन करते हैं: पहले स्पेक की शीर्ष-स्तरीय tags सूची का क्रम, और फिर वे टैग जिन्हें स्पेक घोषित नहीं करता, उसी क्रम में जिसमें ऑपरेशन पहली बार उनका उपयोग करते हैं। किसी टैग के भीतर ऑपरेशन भी स्पेक के क्रम का ही पालन करते हैं: पाथ उसी क्रम में जिसमें वे सूचीबद्ध हैं, और प्रत्येक पाथ के मेथड उसी क्रम में जिसमें वे लिखे गए हैं। किसी टैग के फ़ोल्डर में अपनी pages सूची वाली meta.ts फ़ाइल इस क्रम को ओवरराइड करती है।

किसी टैग का x-displayName (Redocly का एक्सटेंशन) उसके नाम के स्थान पर उसके साइडबार समूह और अवलोकन अनुभाग का लेबल बनता है। टैग का URL फिर भी उसके नाम से ही बनता है, इसलिए इसे जोड़ने से कोई भी पेज अपनी जगह से नहीं हटता। किसी ऑपरेशन का लेबल उसका summary होता है; summary न होने पर लेबल उसका मेथड और पाथ (GET /pets) होता है, ठीक वैसे ही जैसे उसके पेज का शीर्षक बनता है।

स्पेक का info.description अवलोकन पेज की शुरुआत में दिखता है, और प्रत्येक टैग का description वहाँ उसके अनुभाग की शुरुआत में। इनमें लिखे हेडिंग, जहाँ ये दिखते हैं उससे एक स्तर नीचे कर दिए जाते हैं, ताकि पेज का शीर्षक ही उसका एकमात्र शीर्ष-स्तरीय हेडिंग बना रहे: info.description या किसी ऑपरेशन के description में लिखा # Authentication दूसरे स्तर के हेडिंग के रूप में रेंडर होता है, और किसी टैग के विवरण में तीसरे स्तर के हेडिंग के रूप में, यानी टैग के अपने हेडिंग के अंतर्गत।

एक स्थानीय स्पेक

सापेक्ष पाथ आपके प्रोजेक्ट रूट से रिज़ॉल्व किया जाता है और बिल्ड के समय पढ़ा जाता है। JSON और YAML दोनों काम करते हैं, और blume dev इस फ़ाइल पर तथा किसी भी स्थानीय ओवरले पर नज़र रखता है, इसलिए स्पेक सहेजते ही संदर्भ अपडेट हो जाता है:

reference: [openapi({ spec: "./openapi.yaml" })],

OpenAPI 3.2

OpenAPI 3.2 स्पेक ठीक वैसे ही रेंडर होते हैं जैसे वे लिखे गए हैं। HTTP QUERY मेथड (एक सुरक्षित (safe) अनुरोध, जिसमें बॉडी होती है) के लिए बने query ऑपरेशन को किसी भी अन्य मेथड की तरह एक पेज, Try it और कोड नमूने मिलते हैं। 3.2 द्वारा जोड़े गए जिन फ़ील्ड को Blume नहीं दिखाता, जैसे किसी टैग या प्रतिक्रिया का summary, उन्हें अस्वीकार करने के बजाय अनदेखा कर दिया जाता है। 3.2 में जोड़ी गई कुछ चीज़ें अभी रेंडर नहीं होतीं:

• additionalOperations, उन मेथड के लिए जिन्हें कोई पाथ आइटम सीधे नाम से नहीं बताता (जैसे COPY): ऐसे ऑपरेशन छोड़ दिए जाते हैं, और एक BLUME_OPENAPI_UNSUPPORTED चेतावनी दी जाती है।
• in: querystring पैरामीटर: इन्हें न पैरामीटर तालिका में कोई पंक्ति मिलती है, न Try it में कोई इनपुट, और न ही कोड नमूनों में कोई स्थान; इनके लिए भी यही चेतावनी दी जाती है।
• itemSchema, यानी स्ट्रीम की गई बॉडी (text/event-stream, application/jsonl) के प्रत्येक आइटम का स्कीमा: जब तक इसके साथ schema भी सेट न हो, पेज उस बॉडी के लिए कोई स्कीमा नहीं दिखाता।
• value के स्थान पर dataValue या serializedValue से लिखे गए उदाहरण: पेज इन्हें नहीं दिखाता।
• नेस्टेड टैग (parent) और टैग का kind: साइडबार और अवलोकन में टैग एक ही सपाट सूची में रहते हैं।

रूट

route यह नियंत्रित करता है कि संदर्भ कहाँ माउंट होगा। यह अवलोकन पेज का पाथ और प्रत्येक ऑपरेशन रूट का प्रीफ़िक्स तय करता है। नेविगेशन टैब को भी आप इसी रूट की ओर इंगित करते हैं:

reference: [
  openapi({
    route: "/api",   // overview at /api, operations at /api/<tag>/<operation>
    spec: "./openapi.yaml",
  }),
],

किसी ऑपरेशन का <tag> उसका पहला टैग होता है (कोई टैग न होने पर operations), और उसका <operation> उसका operationId होता है, और वह न हो तो उसका मेथड और पाथ। दोनों को लोअरकेस में बदला जाता है और उनके शब्द हाइफ़न से अलग किए जाते हैं, camelCase और PascalCase सहित: टैग InboxesThreads से inboxes-threads बनता है, और operationId listThreads से list-threads। किसी ऑपरेशन का स्लग केवल अपने टैग के भीतर अद्वितीय होना चाहिए, इसलिए दो अलग-अलग टैग में एक-एक list हो सकता है। उसी टैग में आने वाले दूसरे list के साथ उसका मेथड जोड़ दिया जाता है (list-post), और यदि दोनों का operationId एक ही हो, तो एक BLUME_OPENAPI_DUPLICATE_OPERATION_ID चेतावनी दी जाती है।

Blume के पिछले संस्करण टैग के शब्दों को आपस में जोड़कर रखते थे (inboxesthreads) और ऑपरेशन के स्लग को पूरे स्पेक में अद्वितीय बनाते थे (दूसरे list के लिए list-get)। Blume इनमें से प्रत्येक URL को, और उसकी Markdown प्रति को भी, पेज के वर्तमान URL पर रीडायरेक्ट करता है, जब तक कि उस URL पर पहले से कोई पेज या आपके redirects में से कोई प्रविष्टि मौजूद न हो।

कोड नमूने और स्कीमा

codeSamples यह तय करता है कि प्रत्येक ऑपरेशन के लिए किन भाषाओं के नमूने रेंडर हों। नमूने उसी क्रम में दिखते हैं जिसमें आप उन्हें सूचीबद्ध करते हैं। इसका डिफ़ॉल्ट मान ["curl", "js", "python"] है, और false या खाली सूची देने पर कोई भी नमूना नहीं दिखता। expandSchemas नेस्टेड स्कीमा पंक्तियों को संक्षिप्त (collapsed) के बजाय विस्तारित अवस्था में दिखाता है:

reference: [
  openapi({
    spec: "./openapi.yaml",
    codeSamples: ["curl", "python", "go", "java", "csharp"],
    expandSchemas: true,
  }),
],

प्रत्येक नमूना अनुरोध के लिए सादा कोड होता है, जिसे सीधे कॉपी-पेस्ट किया जा सकता है। यह कोड उस भाषा के मानक या सबसे प्रचलित HTTP क्लाइंट से लिखा जाता है:

प्रत्येक मान को उसकी अपनी भाषा के नियमों के अनुसार कोट किया जाता है। इसलिए If-Match: "33a64df5" जैसा हेडर या $ वाली बॉडी API तक ठीक वैसे ही पहुँचती है जैसी लिखी गई है।

जिस आईडी के लिए Blume कोई नमूना जनरेट नहीं करता, जैसे ReadMe का objectivec, उसे हर पेज से छोड़ दिया जाता है, और एक BLUME_OPENAPI_UNKNOWN_CODE_SAMPLE चेतावनी दी जाती है जो ऊपर दी गई आईडी सूचीबद्ध करती है। किसी अन्य भाषा में नमूना दिखाने के लिए, उसे अपने स्वयं के नमूने के रूप में स्पेक में लिखें।

उदाहरणों की तरह ही, स्कीमा तालिकाएँ भी डेटा के प्रवाह की दिशा का पालन करती हैं: अनुरोध बॉडी में readOnly प्रॉपर्टी शामिल नहीं होतीं, क्योंकि उन्हें सर्वर सेट करता है, और प्रतिक्रिया में writeOnly प्रॉपर्टी शामिल नहीं होतीं, क्योंकि सर्वर उन्हें कभी नहीं लौटाता। वेबहुक या कॉलबैक की बॉडी वह अनुरोध है जिसे आपका API भेजता है, इसलिए उसे प्रतिक्रिया की तरह दिखाया जाता है। यही बात अनुरोध नमूनों, Try it फ़ॉर्म और उसमें पहले से भरे मानों, और प्रतिक्रिया उदाहरणों पर भी लागू होती है। इनमें स्पेक में लिखे गए उदाहरण भी शामिल हैं, जैसे मॉडल-स्तर का कोई example जिसमें मॉडल का id हो।

जिस बॉडी या प्रतिक्रिया का examples मैप दो या अधिक उदाहरणों के नाम देता है, उसमें प्रत्येक उदाहरण दिखाया जाता है। प्रत्येक का लेबल उसका summary होता है, या summary न होने पर उसकी कुंजी। प्रतिक्रिया में उसके स्टेटस के बाद प्रत्येक उदाहरण के लिए एक टैब होता है (200 · A cat), वेबहुक पेलोड में उसके मीडिया टाइप के बाद प्रत्येक उदाहरण के लिए एक टैब होता है, और अनुरोध बॉडी में उसके स्कीमा के नीचे एक Examples ब्लॉक होता है। कोड नमूने और Try it पहले उदाहरण से शुरू होते हैं।

$ref के रूप में लिखी गई जिस प्रॉपर्टी के साथ अन्य कीवर्ड भी हों (OpenAPI 3.1 इसकी अनुमति देता है), वह संदर्भित स्कीमा के कीवर्ड के बजाय अपने इन्हीं कीवर्ड को प्राथमिकता देती है। उसकी पंक्ति में उसका अपना description दिखता है, और नमूनों में उसका अपना example या default उपयोग होता है।

आपके अपने नमूने

सीधे HTTP कॉल के बजाय अपना SDK दिखाने के लिए, स्पेक में किसी ऑपरेशन में x-codeSamples जोड़ें। यह Redocly द्वारा परिभाषित एक्सटेंशन है, और Speakeasy तथा Stainless इसे आपके लिए लिख सकते हैं। प्रत्येक प्रविष्टि में एक lang, source और एक वैकल्पिक label होता है:

paths:
  /plants:
    get:
      x-codeSamples:
        - lang: typescript
          label: SDK
          source: |
            const plants = await planter.plants.list();
        - lang: bash
          label: CLI
          source: |
            planter list

ये नमूने जनरेट किए गए नमूनों से पहले, अपने अलग टैब में रेंडर होते हैं। जब पाठक Try it फ़ॉर्म में बदलाव करते हैं, तब भी ये ठीक वैसे ही रहते हैं जैसे लिखे गए थे। पुरानी x-code-samples वर्तनी भी काम करती है। केवल अपने नमूने दिखाने के लिए codeSamples: false सेट करें। जनरेट किए गए नमूनों के विपरीत, ये ऑपरेशन पेज की Markdown प्रति में भी शामिल होते हैं, इसलिए llms-full.txt, MCP सर्वर और असिस्टेंट आपके SDK कॉल देख पाते हैं। यह प्रति अनुरोध बॉडी का मीडिया टाइप और उसकी शीर्ष-स्तरीय प्रॉपर्टी भी उसके उदाहरण (हर नामित उदाहरण) के साथ सूचीबद्ध करती है, और प्रत्येक प्रतिक्रिया का स्टेटस और विवरण भी, स्पेक में दर्ज उदाहरणों के साथ। पहली सफल प्रतिक्रिया के लिए स्पेक में कोई उदाहरण दर्ज न हो, तो उसके लिए स्कीमा से बनाया गया एक उदाहरण जोड़ा जाता है।

source किसी ऐसी फ़ाइल का $ref भी हो सकता है जिसमें नमूने का कोड हो, ठीक उसी तरह जैसे Redocly नमूनों को उनकी अपनी अलग फ़ाइलों में रखने का तरीका बताता है। Blume इस फ़ाइल को स्पेक के सापेक्ष पढ़ता है, और यदि स्पेक एक URL है, तो फ़ाइल को फ़ेच करता है। यदि Blume किसी $ref को पढ़ नहीं पाता, या वह किसी दस्तावेज़ के भीतर (#/…) इंगित करता है, तो वह नमूना छोड़ दिया जाता है और एक BLUME_OPENAPI_CODE_SAMPLE_REF चेतावनी दी जाती है:

paths:
  /plants:
    get:
      x-codeSamples:
        - lang: go
          source:
            $ref: ./code_samples/go/list_plants.go

जनरेट किए गए API दस्तावेज़ीकरण में SDK उदाहरण जोड़ें गाइड एक TypeScript और एक Python SDK के नमूनों को चरण-दर-चरण समझाती है। इसमें एक ऐसी जाँच भी शामिल है जो उन नमूनों को पकड़ लेती है जिन्हें किसी SDK रिलीज़ ने तोड़ दिया हो।

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

नेटिव रूप से रेंडर किए गए ऑपरेशन पेजों में डिफ़ॉल्ट रूप से एक इंटरैक्टिव Try it पैनल शामिल होता है। Blume यह फ़ॉर्म स्वयं ऑपरेशन से जनरेट करता है। इसमें प्रत्येक पाथ, क्वेरी और हेडर पैरामीटर के लिए एक इनपुट और अनुरोध-बॉडी स्कीमा से बना एक बॉडी एडिटर होता है। सब कुछ स्पेक के उदाहरणों से पहले से भरा रहता है। मान ठीक उसी रूप में भेजे जाते हैं जैसा स्पेक उनका वर्णन करता है: ऐरे और ऑब्जेक्ट पैरामीटर अपने style और explode का पालन करते हैं (क्वेरी में tags=dog&tags=cat, पाथ में 1,2, और deepObject के लिए filter[color]=red), और application/x-www-form-urlencoded या multipart/form-data बॉडी JSON के बजाय फ़ॉर्म फ़ील्ड के रूप में भेजी जाती है। एक सर्वर पिकर ऑपरेशन के सर्वर सूचीबद्ध करता है (उसके अपने servers, वे न हों तो उसके पाथ के, और वे भी न हों तो स्पेक के; प्रत्येक {variable} अपने default मान पर रहता है), और किसी अन्य बेस URL के लिए एक मुक्त-पाठ फ़ील्ड भी देता है। ऑथ इनपुट ऑपरेशन की रिज़ॉल्व की गई सुरक्षा से मेल खाते हैं: बेयरर टोकन, API कुंजी और बेसिक क्रेडेंशियल। OAuth2 के लिए एक टोकन पेस्ट फ़ील्ड होता है (एक्सेस टोकन आपको स्वयं लाना होगा; Blume यह फ़्लो नहीं चलाता)।

जब ऑपरेशन की कोई भी प्रतिक्रिया JSON होती है, तो अनुरोध JSON ही माँगते हैं: Send और कोड नमूने एक Accept हेडर भेजते हैं, जिसमें वह पहला JSON मीडिया टाइप होता है जिसे प्रतिक्रियाएँ सूचीबद्ध करती हैं, और सफल प्रतिक्रिया का मीडिया टाइप बाकी से पहले चुना जाता है। Laravel जैसे फ़्रेमवर्क इस हेडर के बिना आए अनुरोध का उत्तर ऐसे देते हैं मानो उसे किसी ब्राउज़र ने भेजा हो: वे बिना प्रमाणीकरण वाली कॉल को, API में प्रलेखित 401 लौटाने के बजाय, किसी लॉगिन पेज पर रीडायरेक्ट कर देते हैं। यदि ऑपरेशन स्वयं कोई Accept हेडर पैरामीटर घोषित करता है, तो इस हेडर के स्थान पर उसी का उपयोग होता है।

पैनल और कोड नमूने हमेशा एक-दूसरे से मेल खाते हैं। फ़ॉर्म में टाइप किए गए मान जनरेट किए गए नमूनों को तुरंत अपडेट कर देते हैं, इसलिए कॉपी की गई curl कमांड ठीक वही अनुरोध करती है जो Send करेगा। यह पैनल पेज पर बोझ भी नहीं बनता। यह सर्वर पर संक्षिप्त (collapsed) अवस्था में रेंडर होता है, और इसका JavaScript केवल तभी लोड होता है जब कोई पाठक इसे पहली बार खोलता है। जो पाठक इसे कभी नहीं खोलते, उन्हें इसका कोई भी हिस्सा डाउनलोड नहीं करना पड़ता।

केवल एक ही मेथड ऐसा है जिसे ब्राउज़र नहीं भेज सकता: TRACE। fetch इसे अस्वीकार कर देता है, इसलिए trace ऑपरेशन पर Send अनुरोध भेजने के बजाय यही बात बताता है, और JavaScript नमूना (जो fetch पर आधारित है) कोड के बजाय एक सूचना के रूप में दिखता है। cURL और Python नमूने इसे बिना किसी समस्या के भेजते हैं।

इसे पूरी तरह बंद करने के लिए केवल playground: false पर्याप्त है:

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

क्रेडेंशियल

ऑथ इनपुट में टाइप किए गए क्रेडेंशियल केवल मेमोरी में रहते हैं और पेज रीलोड होने पर मिट जाते हैं। Remember on this device चुनने पर वे localStorage में सहेजे जाते हैं, और यह भंडारण docs ओरिजिन तक सीमित रहता है। इन्हें कॉल किए जा रहे API के अलावा कहीं और नहीं भेजा जाता। आप कुछ भी टाइप करें, कोड नमूनों में प्लेसहोल्डर (YOUR_TOKEN आदि) ही दिखते रहते हैं, जब तक कि पाठक Include my values in samples चालू न करे।

CORS और प्रॉक्सी

Scalar एम्बेड की तरह ही, अनुरोध सीधे ब्राउज़र से लक्ष्य API तक जाते हैं। इसलिए API को docs साइट से आने वाले क्रॉस-ओरिजिन अनुरोधों की अनुमति देनी होगी (Access-Control-Allow-Origin)। जो API यह अनुमति नहीं दे सकते, उनके लिए playground.proxy सेट करें। इसमें URL देने पर अनुरोध आपके द्वारा होस्ट किए गए प्रॉक्सी से होकर जाते हैं। true देने पर अंतर्निहित /_api-proxy रूट सक्षम होता है (यदि आप basePath सेट करते हैं, तो यह {basePath}/_api-proxy पर होता है)। इसके लिए सर्वर आउटपुट आवश्यक है, यानी एक होस्ट एडैप्टर, जैसे blume/deploy से deployment: vercel():

reference: [
  openapi({
    spec: "./openapi.yaml",
    playground: {
      proxy: true,   // or a URL of your own
    },
  }),
],

अंतर्निहित प्रॉक्सी अनुरोधों को केवल उन्हीं ओरिजिन तक भेजता है जिन्हें आपके स्पेक servers में घोषित करते हैं (दस्तावेज़, पाथ या ऑपरेशन स्तर पर, और वेरिएबल अपने डिफ़ॉल्ट मानों पर), और यह नियम रीडायरेक्ट पर भी लागू होता है। इससे किसी सार्वजनिक docs डिप्लॉयमेंट का उपयोग उसके नेटवर्क के अन्य होस्ट तक पहुँचने के लिए नहीं किया जा सकता। पैनल में टाइप किया गया Custom base URL प्रलेखित सर्वर नहीं माना जाता, इसलिए प्रॉक्सी सक्षम होने पर उस पर भेजे गए अनुरोध 403 के साथ अस्वीकार कर दिए जाते हैं। प्रॉक्सी केवल वही हेडर आगे भेजता है जिन्हें पैनल स्वयं सेट करता है — भरे गए क्रेडेंशियल और हेडर पैरामीटर, Accept हेडर, और बॉडी का Content-Type। इसलिए कुकीज़, docs साइट के लिए ब्राउज़र द्वारा जोड़े गए क्रेडेंशियल (जैसे पासवर्ड-सुरक्षित प्रीव्यू पर HTTP Basic ऑथ), और आपके होस्ट द्वारा जोड़े गए हेडर (X-Forwarded-For, CF-*, X-Vercel-*) कभी भी API तक नहीं पहुँचते। प्रॉक्सी अनुरोध बॉडी को केवल 4 MB तक पढ़ता है; इससे बड़े अनुरोध को 413 मिलता है। यह जो भी प्रतिक्रिया आगे भेजता है, उसमें Content-Security-Policy: sandbox, X-Content-Type-Options: nosniff और Cross-Origin-Resource-Policy: same-origin हेडर होते हैं। HTML या SVG प्रतिक्रियाओं में Content-Disposition: attachment भी जुड़ता है। इस तरह, अपना इनपुट वापस दिखाने वाला कोई API त्रुटि पेज docs ओरिजिन पर स्क्रिप्ट नहीं चला सकता। पाठक द्वारा कॉल किए जा सकने वाले हर सर्वर रूट की तरह, प्रॉक्सी पर भी प्रति पाठक रेट लिमिट लागू होती है।

जब कोई Try it अनुरोध ब्लॉक हो जाता है, तो API दस्तावेज़ीकरण प्लेग्राउंड में CORS त्रुटियाँ ठीक करें गाइड उस समस्या को दोबारा उत्पन्न करती है और ब्राउज़र द्वारा भेजे जाने वाले प्रीफ़्लाइट अनुरोध को पढ़ती है। फिर यह आपके API पर एक CORS नीति या अंतर्निहित प्रॉक्सी के माध्यम से उसे ठीक करती है।

एकाधिक स्पेक

एक ही एडैप्टर से एक से अधिक स्पेक प्रकाशित करने के लिए sources का उपयोग करें। प्रत्येक स्रोत को अपना अवलोकन रूट और ऑपरेशन पेज मिलते हैं, जबकि डिस्प्ले विकल्प एडैप्टर से साझा होते हैं। प्रत्येक स्रोत को एक label दें (यह बिना किसी बदलाव के साइडबार में उसके समूह का नाम बनता है, और इसी से उसका रूट बनता है), या एक स्पष्ट route सेट करें:

reference: [
  openapi({
    sources: [
      { label: "Public API", spec: "./public.json" },   // → /reference/public-api
      { label: "Admin API", route: "/admin", spec: "./admin.json" },
    ],
  }),
],

किसी स्रोत का समूह उसके रूट पर स्थित होता है, और उस रूट के ऊपर का प्रत्येक फ़ोल्डर भी एक साइडबार समूह होता है। इसलिए किसी स्पेक को उसी फ़ोल्डर पर रूट करें जिसका वह वर्णन करता है: route: "/apis/messaging" स्रोत के समूह को messaging फ़ोल्डर का अपना समूह बना देता है, जिसका नाम उसके label से आता है, जबकि "/apis/messaging/openapi" उस समूह को एक Messaging समूह के भीतर नेस्ट कर देता है, जिसमें और कुछ नहीं होता।

spec एकल-प्रविष्टि वाले sources का संक्षिप्त रूप है, इसलिए sources की आवश्यकता केवल तभी होती है जब आपके पास एक से अधिक स्पेक हों। यदि दो स्पेक को अलग-अलग डिस्प्ले विकल्प चाहिए, जैसे कोड नमूनों का अलग सेट, तो इसके बजाय दो openapi() एडैप्टर सूचीबद्ध करें और प्रत्येक को अपना route दें। नेटिव पेजों के साथ एम्बेड किया गया Scalar संदर्भ सूची में एक अलग scalar() एडैप्टर के रूप में जोड़ा जाता है। स्रोत सूची के क्रम में रिज़ॉल्व किए जाते हैं। यदि दो स्रोत एक ही रूट पर रिज़ॉल्व होते हैं, तो पहला स्रोत रखा जाता है, और बिल्ड छोड़े गए स्रोत के बारे में चेतावनी देता है।

एक ही docs साइट में एकाधिक OpenAPI स्पेक मिलाएँ गाइड इसी तरह एक API पोर्टल बनाती है, जिसमें प्रत्येक सर्विस का स्पेक अपने अलग रूट और टैब पर होता है।

प्रति-स्रोत इंडेक्सिंग

जनरेट किए गए पेज डिफ़ॉल्ट रूप से खोज, llms.txt और क्रॉलर इंडेक्सिंग में शामिल होते हैं। कोई द्वितीयक या ओवरलैपिंग स्पेक इनमें से किसी से भी बाहर रह सकता है। इससे उसके पेज छिपते नहीं हैं और वह नेविगेशन में भी बना रहता है:

reference: [
  openapi({
    sources: [
      { label: "Public API", route: "/api", spec: "./public.json" },
      {
        label: "Platform API",
        route: "/platform",
        spec: "./platform.json",
        includeInSearch: false,
        includeInLlms: false,
        noindex: true,
      },
    ],
  }),
],

• includeInSearch: false स्रोत के अवलोकन और ऑपरेशनों को साइट खोज से बाहर रखता है।
• includeInLlms: false उन्हें दोनों llms.txt फ़ाइलों से बाहर रखता है।
• noindex: true क्रॉलर noindex मेटाडेटा जोड़ता है और पेजों को साइटमैप से हटा देता है।

प्रत्येक ऑपरेशन पेज का meta description ऑपरेशन का अपना description (या summary) होता है। इसके बाद एक जनरेट किया गया वाक्य जुड़ता है जो एंडपॉइंट का नाम बताता है — “Reference for the GET /pets endpoint in the Petstore API.”। इस तरह, छोटे एक-पंक्ति सारांशों वाले स्पेक से भी प्रत्येक पेज को अलग और स्निपेट के लायक लंबाई का विवरण मिलता है। यह वाक्य अंग्रेज़ी में होता है। यदि आपके स्पेक का पाठ किसी अन्य भाषा में लिखा गया है, तो स्रोत पर seoDescriptionSuffix: false सेट करें। इससे यह वाक्य हट जाता है और प्रत्येक पेज का विवरण केवल आपके लिखे पाठ से बनता है। जिस ऑपरेशन में न description हो और न summary, उसके लिए उसका शीर्षक (GET /pets) उपयोग होता है, ताकि किसी भी पेज का विवरण खाली न रहे:

reference: [
  openapi({
    sources: [{ spec: "./openapi.de.json", seoDescriptionSuffix: false }],
  }),
],

scalar() एम्बेड इनमें से केवल noindex स्वीकार करता है। यह पहले से ही Blume की खोज और llms.txt से बाहर रहता है, इसलिए दोनों include* सेटिंग्स का वहाँ कोई प्रभाव नहीं होता।

ओवरले

जब स्पेक किसी अन्य टूल द्वारा जनरेट किया जाता है या किसी अन्य टीम के स्वामित्व में होता है, तो docs के लिए अपने बदलाव उसमें सीधे करने के बजाय OpenAPI Overlay का उपयोग करें। यह एक अलग फ़ाइल होती है जो स्पेक में किए जाने वाले बदलावों को सूचीबद्ध करती है, जैसे अधिक स्पष्ट विवरण, एक सार्वजनिक सर्वर URL, या आंतरिक ऑपरेशनों को हटाना। ओवरले को spec के साथ सूचीबद्ध करें। प्रत्येक ओवरले एक स्थानीय पाथ या एक http(s) URL होता है, और वे क्रम से लागू होते हैं:

reference: [
  openapi({
    spec: "./openapi.json",
    overlays: ["./overlays/public.yaml"],
  }),
],

overlay: 1.1.0
info:
  title: Public docs
  version: 1.0.0
actions:
  - target: $.paths.*[?@['x-internal'] == true]
    remove: true
  - target: $.info
    update:
      description: The public Acme API.

प्रत्येक एक्शन का target एक JSONPath एक्सप्रेशन होता है। update अपने द्वारा चुने गए प्रत्येक नोड में मर्ज होता है: ऑब्जेक्ट कुंजी-दर-कुंजी मर्ज होते हैं, ऐरे में नए आइटम जुड़ जाते हैं, और अन्य मान बदल दिए जाते हैं। copy स्पेक में किसी अन्य स्थान से एक नोड लाकर मर्ज करता है (Overlay 1.1), और remove: true लक्ष्यों को हटा देता है। Overlay Specification 1.0 और 1.1 दोनों समर्थित हैं।

ओवरले स्पेक पर उसी रूप में लागू होते हैं जैसा वह लिखा गया है, यानी Blume द्वारा उसे OpenAPI 3.1 में अपग्रेड करने से पहले। इसलिए ओवरले को उसी संस्करण के अनुसार लिखें जिसमें आपका स्पेक लिखा गया है। स्पेक से बनने वाली हर चीज़ में इसका परिणाम दिखता है: ऑपरेशन पेज, साइडबार, खोज, llms.txt और MCP सर्वर। sources का उपयोग करते समय प्रत्येक स्रोत को उसके अपने overlays दें। जो ओवरले लागू नहीं हो पाता, वह संदर्भ को उसी तरह विफल कर देता है जैसे कोई अपठनीय स्पेक करता है। इस तरह, कोई टूटा हुआ ओवरले वह सामग्री प्रकाशित नहीं कर सकता जिसे छिपाने के लिए वह बनाया गया था।

सार्वजनिक API दस्तावेज़ों से आंतरिक एंडपॉइंट हटाएँ गाइड एक ऐसे ओवरले को चरण-दर-चरण समझाती है जो हर बिल्ड पर जनरेट किए गए स्पेक से आंतरिक ऑपरेशन हटा देता है।

प्राधिकरण

जो ऑपरेशन सुरक्षा आवश्यकताएँ घोषित करते हैं, उनके पैरामीटर के ऊपर एक Authorization अनुभाग दिखता है। जनरेट किए गए कोड नमूने स्कीम के अनुसार एक प्लेसहोल्डर क्रेडेंशियल भेजते हैं: Authorization: Bearer YOUR_TOKEN, एक API-कुंजी हेडर, या एक क्वेरी कुंजी। इसके लिए कुछ भी कॉन्फ़िगर नहीं करना पड़ता। Blume स्पेक से security पढ़ता है, इसलिए संदर्भ हमेशा उन्हीं नियमों को दिखाता है जो API वास्तव में लागू करता है।

OpenAPI के नियम स्पेक में लिखे अनुसार ही लागू होते हैं:

• किसी ऑपरेशन का अपना security दस्तावेज़ के रूट डिफ़ॉल्ट को ओवरराइड करता है। security: [] उसे सार्वजनिक चिह्नित करता है, और उसके लिए कोई Authorization अनुभाग नहीं दिखता।
• एकाधिक आवश्यकता प्रविष्टियाँ आपस में विकल्प होती हैं और “या” समूहों के रूप में दिखती हैं। एक प्रविष्टि के भीतर की सभी स्कीम एक साथ आवश्यक होती हैं। कोड नमूने पहले विकल्प पर आधारित होते हैं।
• खाली {} प्रविष्टि का अर्थ है कि उस ऑपरेशन के लिए ऑथ वैकल्पिक है, और अनुभाग में यह बात बताई जाती है।
• OAuth2 स्कोप प्रत्येक स्कीम के अनुसार सूचीबद्ध होते हैं। components.securitySchemes में दिए गए स्कीम के description इनलाइन दिखाए जाते हैं।

वेबहुक और कॉलबैक

आपके API से बाहर जाने वाले अनुरोधों का भी दस्तावेज़ीकरण होता है। स्पेक के शीर्ष-स्तरीय webhooks में मौजूद प्रत्येक वेबहुक को किसी ऑपरेशन की तरह अपना पेज मिलता है। यह पेज वेबहुक के पहले टैग के अंतर्गत रखा जाता है, और कोई टैग न होने पर Webhooks समूह में। पेज पर पेलोड का स्कीमा और वे प्रतिक्रियाएँ दिखती हैं जो आपके एंडपॉइंट को वापस भेजनी चाहिए। Try it पैनल और कोड नमूनों के स्थान पर साइड रेल में एक उदाहरण पेलोड दिखता है, क्योंकि आपका API यह अनुरोध प्राप्त नहीं करता, बल्कि भेजता है। वेबहुक पेज केवल वही security सूचीबद्ध करता है जिसे वेबहुक स्वयं घोषित करता है। स्पेक का रूट security आपके API पर की जाने वाली कॉल को सुरक्षित करता है, इसलिए यह API द्वारा भेजे जाने वाले अनुरोधों पर लागू नहीं होता। जो वेबहुक किसी साझा पाथ आइटम का $ref है, उसे छोड़ दिया जाता है और एक BLUME_OPENAPI_REF_PATH_ITEM चेतावनी दी जाती है।

webhooks:
  newPet:
    post:
      summary: New pet added
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 to acknowledge the event.

किसी 3.0 स्पेक में x-webhooks एक्सटेंशन के अंतर्गत रखे गए वेबहुक, Blume द्वारा स्पेक को 3.1 में अपग्रेड करते समय webhooks बन जाते हैं। जो स्पेक पहले से 3.1 या उसके बाद के संस्करण में है, उसे अपग्रेड नहीं किया जाता। इसलिए यदि वह अपने वेबहुक अब भी x-webhooks के अंतर्गत रखता है, तो उनमें से कुछ भी रेंडर नहीं होता और एक BLUME_OPENAPI_X_WEBHOOKS चेतावनी दी जाती है: फ़ील्ड का नाम बदलकर webhooks करें।

किसी ऑपरेशन के callbacks वे अनुरोध हैं जो आपका API कॉलर द्वारा दिए गए URL पर वापस भेजता है। ये उस ऑपरेशन के पेज पर एक Callbacks अनुभाग में रेंडर होते हैं। प्रत्येक कॉलबैक अपना URL एक्सप्रेशन ({$request.body#/callbackUrl}), मेथड, पैरामीटर (जैसे कोई सिग्नेचर हेडर), अनुरोध बॉडी और अपेक्षित प्रतिक्रियाएँ दिखाता है। components.callbacks के अंतर्गत घोषित और $ref से संदर्भित कॉलबैक भी इसी तरह काम करते हैं।

वेबहुक पेज वास्तविक पेज होते हैं: वे खोज, llms.txt और MCP सर्वर में शामिल होते हैं। उनका Markdown एजेंटों को बताता है कि यह अनुरोध API भेजता है, ताकि कोई एजेंट इसे कॉल करने का प्रयास न करे।

OpenAPI 3.1 के साथ वेबहुक दस्तावेज़ीकरण लिखें गाइड वेबहुक पेजों में सिग्नेचर हेडर और पावती (acknowledgment) जोड़ती है। साथ ही यह वेबहुक प्राप्त करने के लिए एक गाइड भी जोड़ती है, जिसमें एक कार्यशील Node.js रिसीवर शामिल है।

स्पेक चेतावनियाँ

Blume किसी स्पेक को OpenAPI स्कीमा के विरुद्ध सत्यापित नहीं करता। इसके लिए CI में Spectral या oasdiff जैसा कोई लिंटर चलाएँ। हालाँकि, blume dev, blume build और blume check में यह उन गलतियों के बारे में चेतावनी देता है जो अन्यथा बिना किसी संकेत के गलत रेंडर होतीं, और स्पेक के उन हिस्सों के बारे में भी जिन्हें यह छोड़ देता है। प्रत्येक चेतावनी में स्पेक का नाम होता है, और संदर्भ का शेष भाग फिर भी बिल्ड होता है:

CI में API दस्तावेज़ीकरण को बैकएंड बदलावों के साथ सिंक में रखें गाइड ये जाँचें GitHub Actions में चलाती है। यह बैकएंड से स्पेक एक्सपोर्ट करती है, और यदि स्पेक पुराना, अमान्य या ब्रेकिंग है, तो विफल हो जाती है। फिर यह उसी स्पेक से संदर्भ को दोबारा बिल्ड करती है।

अपने पेजों में ऑपरेशन

कोई भी MDX पेज <Operation> के माध्यम से किसी संदर्भ का ऑपरेशन दिखा सकता है: उसका प्राधिकरण, पैरामीटर, अनुरोध बॉडी और प्रतिक्रियाएँ, Try it पैनल और कोड नमूनों के साथ, ठीक वैसे ही जैसे ऑपरेशन का अपना पेज उन्हें दिखाता है। इस तरह कोई क्विकस्टार्ट पाठकों को कहीं और भेजे बिना उसी एक कॉल को चरण-दर-चरण समझा सकता है जिसके बारे में वह है:

---
title: Quickstart
mode: wide
---

Create your first pet:

<Operation source="reference" id="add-pet" />

source संदर्भ को उसके रूट से पहचानता है, बिना स्लैश के, लोअरकेस में और हाइफ़न के साथ (/reference का reference, और /api/v2 का api-v2)। id ऑपरेशन को पहचानता है: उसका operationId, लोअरकेस में और शब्दों को हाइफ़न से अलग करके (addPet का add-pet), या operationId न होने पर उसका मेथड और पाथ (post-pets)। दोनों मान पाने का सबसे पक्का तरीका ऑपरेशन पेज की कच्ची MDX प्रति है, जो उसके URL के अंत में .mdx जोड़ने पर मिलती है; उसकी बॉडी ही वह टैग है जिसे आपको कॉपी करना है। ऑपरेशन दो कॉलम में दिखता है, इसलिए पेज को mode: wide दें: विषय-सूची के साथ बायाँ कॉलम संकरा रह जाता है। पेज की Markdown प्रति में यह टैग एंडपॉइंट, अनुरोध बॉडी और प्रतिक्रियाओं में बदल जाता है, ठीक वैसे ही जैसे ऑपरेशन के अपने पेज पर।

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

openapi() हमेशा Blume के अपने पेज रेंडर करता है। आप चाहें तो किसी एक रूट पर Scalar का स्व-निहित API संदर्भ UI एम्बेड कर सकते हैं, जिसका अपना साइडबार, खोज, थीम और अनुरोध क्लाइंट होता है। इसके लिए इस एडैप्टर के स्थान पर (या इसके साथ) blume/reference से एक scalar() एडैप्टर सूचीबद्ध करें। Scalar पेज बताता है कि एम्बेड क्या करता है और क्या नहीं। वहाँ यह भी बताया गया है कि Scalar के अपने विकल्प कैसे पास करें।