api-docs-writer

# machine-translated to hi from skills/api-docs-writer/SKILL.md — review: pending. Native fixes welcome via PR.name: api-docs-writerdescription: "डेवलपर्स के लिए स्पष्ट API दस्तावेज़ लिखें। जब कोई API एंडपॉइंट दस्तावेज़ित करने, API रेफ़रेंस डॉक्स लिखने, डेवलपर गाइड बनाने या कच्चे स्पेक/Postman कलेक्शन को दस्तावेज़ में बदलने को कहे, तब इसका उपयोग करें। विवरण, पैरामीटर, रिक्वेस्ट/रिस्पॉन्स उदाहरण और एरर कोड के साथ एंडपॉइंट दस्तावेज़ तैयार करता है।"

API डॉक्स राइटर स्किल

यह स्किल कच्चे API स्पेक, एंडपॉइंट विवरण या Postman कलेक्शन को OpenAPI से मिलती-जुलती परंपराओं के अनुसार साफ़, डेवलपर-केंद्रित दस्तावेज़ में बदलती है। आउटपुट डेवलपर पोर्टल, README या Notion/Confluence पेज के लिए तैयार होता है।

आवश्यक इनपुट

जो दिया गया है उसी से काम करें। इनमें से कुछ न हो तो भी पूरा आउटपुट बनाएँ: हर खाली जगह को (माना गया, पुष्टि करें) चिह्नित एक उचित धारणा से भरें और अंत में उन धारणाओं की सूची दें। सवाल पहले सिर्फ़ तब पूछें जब मुख्य विषय ही न हो (लिखने के लिए कुछ हो ही नहीं)।

• API या एंडपॉइंट का विवरण (कच्चा स्पेक, Postman एक्सपोर्ट, या मौखिक विवरण)
• प्रमाणीकरण विधि (API key / Bearer token / OAuth 2.0 / कोई नहीं)
• बेस URL
• API संस्करण (जैसे v1, v2.3, या "unversioned" — डेप्रिकेशन नोट और वर्ज़निंग हेडर पर असर डालता है)
• रेट लिमिट (प्रति टोकन या IP प्रति सेकंड/मिनट अनुरोध, अगर ज्ञात हो — या "अज्ञात")
• श्रोता (आंतरिक डेवलपर / बाहरी पार्टनर / सार्वजनिक)
• आउटपुट फ़ॉर्मैट (डेवलपर पोर्टल और README के लिए Markdown / Confluence या Notion के लिए सादा गद्य — ध्यान दें: यह स्किल OpenAPI YAML नहीं बनाती)

आउटपुट फ़ॉर्मैट

हर एंडपॉइंट के लिए निम्न तैयार करें:

---

[METHOD] /path/to/endpoint

सारांश: [एक पंक्ति — यह एंडपॉइंट क्या करता है]

विवरण: [2–4 वाक्य। इस एंडपॉइंट का उपयोग कब करें। यह क्या लौटाता है। जानने लायक कोई महत्वपूर्ण व्यवहार (पेजिनेशन, रेट लिमिट, async प्रोसेसिंग आदि)]

प्रमाणीकरण: [आवश्यक / वैकल्पिक — विधि]

---

रिक्वेस्ट

हेडर:

पाथ पैरामीटर:

क्वेरी पैरामीटर:

रिक्वेस्ट बॉडी:

{
  "field_name": "value",
  "another_field": 42
}

---

रिस्पॉन्स

सफल रिस्पॉन्स: 200 OK

{
  "id": "abc123",
  "status": "active",
  "created_at": "2025-04-01T10:00:00Z"
}

---

एरर कोड

---

कोड उदाहरण

श्रोताओं के लिए प्रासंगिक कम से कम 2 भाषाओं में उदाहरण दें (डिफ़ॉल्ट: cURL + Python):

cURL:

curl -X POST https://api.example.com/v1/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "value"}'

Python:

import requests

response = requests.post(
    "https://api.example.com/v1/endpoint",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"field_name": "value"}
)
data = response.json()

---

गहरी सामग्री

यह स्किल सहायक फ़ाइलों के साथ आती है — उपलब्ध हों तो उनका उपयोग करें:

• references/example-first-docs.md — उदाहरण-प्रथम API डॉक्स: वे नियम जो दस्तावेज़ को उपयोगी बनाते हैं। आउटपुट बनाते समय इसे लागू करें; इसमें वह कैलिब्रेशन और निर्णय-विवेक है जिसे ऊपर का संक्षिप्त तरीका संकुचित कर देता है।
• templates/endpoint-entry.md — डिलिवरेबल का भरने योग्य संस्करण, गुणवत्ता-जाँच इनलाइन सहित। जब उपयोगकर्ता दस्तावेज़ खुद बनाना चाहे, उसे जनरेट करवाने के बजाय, तब यह पेश करें।

स्कोरिंग रूब्रिक (0–40)

इस स्किल का कोई भी आउटपुट सौंपने से पहले स्कोर करें; 32+ शिप-गुणवत्ता है।

गुणवत्ता जाँच

• हर पैरामीटर दस्तावेज़ित है (प्रकार, आवश्यक/वैकल्पिक, विवरण)
• रिस्पॉन्स फ़ील्ड प्रकार सहित पूरी तरह दस्तावेज़ित हैं
• सभी प्रासंगिक एरर कोड समाधान मार्गदर्शन के साथ सूचीबद्ध हैं
• एरर कोड कम से कम कवर करते हैं: 400 (bad request), 401/403 (auth), 404 (not found), 429 (rate limited), 500 (server error) — या स्पष्ट रूप से बताया गया है कि इस एंडपॉइंट पर कौन से लागू नहीं होते
• कोड उदाहरण वास्तविक बेस URL और यथार्थवादी प्लेसहोल्डर टोकन का उपयोग करते हैं — कोई उदाहरण स्निपेट के बाहर अपरिभाषित वेरिएबल या "YOUR_ENDPOINT" का संदर्भ नहीं देता
• प्रमाणीकरण विधि ऊपर स्पष्ट रूप से बताई गई है
• जहाँ लागू हो, enum मान सूचीबद्ध हैं
• अगर एंडपॉइंट सूची लौटाता है, तो पेजिनेशन दस्तावेज़ित है

एंटी-पैटर्न

• सिर्फ़ सुखद पथ दस्तावेज़ित न करें — हर एंडपॉइंट में कम से कम 400, 401/403, 404, 429 और 500 के एरर कोड होने चाहिए
• कोड उदाहरणों में "YOUR_ENDPOINT" या "INSERT_TOKEN" जैसे प्लेसहोल्डर मान न लिखें — वास्तविक बेस URL से जुड़े यथार्थवादी प्लेसहोल्डर उपयोग करें
• जिन फ़ील्ड के स्वीकार्य मानों का सेट तय है, उनके enum मान न छोड़ें — अदस्तावेज़ित enum इंटीग्रेशन बग पैदा करते हैं
• सूची एंडपॉइंट पर पेजिनेशन का दस्तावेज़ न छोड़ें — जो डेवलपर इसे चूकेंगे, वे ऐसे इंटीग्रेशन बनाएँगे जो चुपचाप डेटा खो देंगे
• फ़ील्ड "क्या है" बताकर "क्या करता है" बताना न छोड़ें — "ID" दस्तावेज़ नहीं है; "इस संसाधन को प्राप्त या अपडेट करने में प्रयुक्त अद्वितीय पहचानकर्ता" है

उपयोग के उदाहरण

• "इस API एंडपॉइंट को दस्तावेज़ित करो: [स्पेक या विवरण पेस्ट करें]"
• "इस Postman कलेक्शन को डेवलपर डॉक्स में बदलो"
• "[एंडपॉइंट] के लिए API रेफ़रेंस डॉक्स लिखो"
• "हमारे [प्रोडक्ट] API के लिए डेवलपर गाइड लिखो"

उदाहरण ट्रिगर वाक्य

• "एक API एंडपॉइंट दस्तावेज़ित करो।"
• "API रेफ़रेंस डॉक्स लिखो।"
• "एक डेवलपर गाइड बनाओ।"
• "कच्चे स्पेक/Postman कलेक्शन को दस्तावेज़ में बदलो।"

इस स्किल को अपने ब्राउज़र में चलाएँ: https://mohitagw15856.github.io/pm-claude-skills/skill/api-docs-writer.html