हाथ से लिखे API पेज

बिना spec के MDX में किसी endpoint का दस्तावेज़ लिखें, और फिर भी method और path, Try it पैनल, अनुरोध के नमूने और पिन किए गए उदाहरण पाएँ।

हर API के पास OpenAPI spec नहीं होता, और कुछ endpoints हाथ से लिखे जाने पर अधिक पठनीय होते हैं। api frontmatter वाला पेज एक endpoint का दस्तावेज़ होता है। इसके फ़ील्ड अनुरोध और प्रतिक्रिया का वर्णन करते हैं। Blume इन्हीं से OpenAPI संदर्भ पेज का बाकी हिस्सा बनाता है: सबसे ऊपर method और path, सामग्री के बगल वाले कॉलम में Try it पैनल और अनुरोध के नमूने, और उनके नीचे पिन किए गए अनुरोध और प्रतिक्रिया के उदाहरण।

---
title: Create a user
api: POST /workspaces/{workspaceId}/users
---

Creates a user and sends them an invite.

<ParamField path="workspaceId" type="string" required>
  The workspace to add the user to.
</ParamField>

<ParamField body="email" type="string" required placeholder="ada@example.com">
  The user's email address.
</ParamField>

<ParamField body="role" type="string" default="member">
  One of `owner`, `admin`, or `member`.
</ParamField>

<ResponseField name="id" type="string" required>
  The new user's ID.
</ResponseField>

<ResponseExample>

```json 201
{ "id": "usr_8f2k", "status": "invited" }
```

</ResponseExample>

api में एक HTTP method के साथ path या पूरा URL दिया जाता है। Path पैरामीटर braces में लिखे जाते हैं, जैसे {workspaceId}, और इनका मान उसी नाम वाले path फ़ील्ड से भरा जाता है। पूरा URL, जैसे GET https://api.acme.com/v1/users, दिया गया हो तो अनुरोध ठीक उसी पर भेजा जाता है जैसा वह लिखा गया है। Path दिया गया हो तो वह साइट के api.server के साथ जोड़ा जाता है।

Playground और नमूने

Spec में जैसे किसी operation के पैरामीटर Try it पैनल के इनपुट बनते हैं, वैसे ही यहाँ पेज के ParamField बनते हैं। path, query और header फ़ील्ड पैरामीटर होते हैं। body फ़ील्ड मिलकर JSON body बनाते हैं। किसी फ़ील्ड के भीतर नेस्ट किए गए फ़ील्ड (उसके Expandable के अंदर) एक object की properties बनते हैं। string[] वाला type एक array होता है। जो type JSON type नहीं है, जैसे enum<string>, वह string के रूप में भेजा जाता है। किसी फ़ील्ड का default मान body में भरा जाता है, और उसका placeholder वह उदाहरण मान है जो नमूनों में दिखता है।

पैनल के बगल में पेज पर cURL, JavaScript और Python में अनुरोध के नमूने दिखते हैं। अगर पेज का अपना RequestExample हो, तो इन नमूनों की जगह वही दिखता है।

दो और frontmatter keys से आप पेज को अपनी ज़रूरत के अनुसार ढाल सकते हैं:

authMethod तय करता है कि endpoint प्रमाणीकरण कैसे करता है: bearer, basic, key (header में भेजी गई API key) या none। यह साइट के api.auth पर प्राथमिकता लेता है।
playground तय करता है कि पेज पर क्या दिखे: Try it पैनल और नमूनों के लिए interactive (डिफ़ॉल्ट), केवल नमूनों के लिए simple, या इनमें से कुछ भी न दिखाने के लिए none। Method, path और उदाहरण हर हाल में दिखते रहते हैं।

साइट डिफ़ॉल्ट

blume.config.ts में api वे सेटिंग्स तय करता है जो सभी endpoint पेजों पर एक जैसी लागू होती हैं:

export default defineConfig({
  api: {
    server: "https://api.acme.com/v1",
    auth: { method: "key", name: "x-api-key" },
    playground: { proxy: true },
  },
});

server वह base URL है जिसके साथ api का path जोड़ा जाता है।
auth तय करता है कि अनुरोधों का प्रमाणीकरण कैसे हो। जिस पेज पर authMethod सेट हो, वहाँ authMethod ही लागू होता है। method का मान bearer, basic, key या none होता है। name उस header का नाम है जिसमें API key भेजी जाती है (डिफ़ॉल्ट रूप से x-api-key)। auth सेट न हो तो पेज कोई क्रेडेंशियल नहीं भेजते।
playground के मान वही हैं जो OpenAPI संदर्भ के playground विकल्प के हैं। false हर पेज से Try it पैनल हटा देता है। proxy पैनल के अनुरोधों को CORS proxy से भेजता है। इसके लिए आप अपने proxy का URL दे सकते हैं, या Blume का बिल्ट-इन proxy इस्तेमाल करने के लिए true दे सकते हैं। बिल्ट-इन proxy के लिए सर्वर आउटपुट ज़रूरी है। यह अनुरोध केवल server के origin पर और api frontmatter में दिए गए पूरे URLs के origins पर ही आगे भेजता है।

पेज का लेआउट, फ़ील्ड और उदाहरण वही कंपोनेंट हैं जो बाकी जगहों पर इस्तेमाल होते हैं। इसलिए पेज की Markdown कॉपी में हर फ़ील्ड सूचीबद्ध होता है, और सर्च इस पेज को बाकी पेजों की तरह ही इंडेक्स करता है।

Frontmatter keys और कंपोनेंट props वही हैं जो Mintlify में हैं, इसलिए Mintlify के लिए लिखे गए पेज बिना किसी बदलाव के काम करते रहते हैं।