Claude Code के साथ व्यवहार से OpenAPI बनाएं, ईमानदारी से

क्यों OpenAPI अनुबंध डिफ्ट करते हैं (और इससे फर्क क्यों पड़ता है)

एक OpenAPI अनुबंध आपकी API का साझा विवरण है: कौन‑से endpoints हैं, आप क्या भेजते हैं, क्या वापस मिलता है, और errors कैसे दिखते हैं। यह सर्वर और उसे कॉल करने वाली किसी भी चीज़ (वेब ऐप, मोबाइल ऐप, या दूसरी सेवा) के बीच समझौता है।

समस्या है ड्रिफ्ट। चल रही API बदलती है, लेकिन स्पेक नहीं बदलता। या स्पेक “साफ़-सुथरा” दिखने के लिए reality से अलग हो जाता है, जबकि implementation अजीब फ़ील्ड्स लौटाती रहती है, status codes गायब होते हैं, या error shapes inconsistent होते हैं। समय के साथ लोग OpenAPI फ़ाइल पर भरोसा करना बंद कर देते हैं, और वह बस एक और docs बन जाती है जिसे कोई नहीं पढ़ता।

ड्रिफ्ट आमतौर पर सामान्य दबावों से आता है: एक quick fix बिना स्पेक अपडेट किए भेज दिया जाता है, कोई नया optional फ़ील्ड अस्थायी रूप से जोड़ा जाता है, pagination विकसित होती है, या टीमें अलग‑अलग “sources of truth” (backend कोड, एक Postman collection, और एक OpenAPI फ़ाइल) अपडेट करती हैं।

इमानदार बनाए रखने का मतलब है कि स्पेक वास्तविक व्यवहार से मेल खाता हो। यदि API कभी‑कभी conflict के लिए 409 लौटाती है, तो वह अनुबंध में होना चाहिए। यदि कोई फ़ील्ड nullable है, तो बताइए। यदि auth चाहिए, उसे vague न छोड़ें।

एक अच्छा workflow आपको ये देता है:

• एक OpenAPI फ़ाइल जो इरादे और अवलोकित व्यवहार दोनों को दर्शाती है
• ड्रिफ्ट को जल्दी पकड़ने के लिए सरल चेक्स का सेट, इससे पहले कि क्लाइंट्स टूटें
• प्रतिलिपि के रूप में अपने कोडबेस में डालने लायक व्यवहारी क्लाइंट और सर्वर वैलिडेशन उदाहरण

अंतिम बात महत्वपूर्ण है क्योंकि एक अनुबंध तब ही मदद करता है जब उसे लागू किया जाए। एक ईमानदार स्पेक और दोहराए जाने वाले चेक्स "API documentation" को ऐसी चीज़ में बदल देते हैं जिस पर टीमें भरोसा कर सकती हैं।

कोड से नहीं, इरादे से शुरू करें

यदि आप कोड पढ़कर या routes कॉपी करके शुरू करते हैं, तो आपका OpenAPI वही बताएगा जो आज मौजूद है, जिसमें वे quirks भी होंगे जिन्हें आप वादा नहीं करना चाहते। इसके बजाय, बताइए कि API caller के लिए क्या करना चाहिए, फिर स्पेक का उपयोग करके verify करें कि implementation मैच करती है।

YAML या JSON लिखने से पहले, हर endpoint के लिए कुछ तथ्य इकट्ठा करें:

• यह क्या करता है (method और path)
• यह क्या स्वीकार करता है (headers, query, path params, body)
• यह क्या लौटाता है (success status code, response shape, प्रमुख headers)
• क्या fail कर सकता है (संभावित errors, status codes, error body shape)
• कौन इसे कॉल कर सकता है (auth और roles, यदि प्रासंगिक)

फिर व्यवहार को examples के रूप में लिखें। उदाहरण आपको specific होने पर मजबूर करते हैं और एक सुसंगत अनुबंध ड्राफ्ट करना आसान बनाते हैं।

एक Tasks API के लिए, एक happy path उदाहरण हो सकता है: “title के साथ एक task बनाएं और id, title, status, और createdAt वापस पाएं।” सामान्य failures जोड़ें: “title गायब होने पर 400 लौटता है { "error": "title is required" }” और “auth नहीं होने पर 401।” यदि आपको edge cases पहले से पता हैं तो उन्हें शामिल करें: duplicate titles की अनुमति है या नहीं, और जब कोई task ID मौजूद नहीं होती तो क्या होता है।

नियमों को साधारण वाक्यों में कैप्चर करें जो कोड विवरणों पर निर्भर न हों:

• “title required है और 1-120 characters का होना चाहिए।”
• “List अधिकतम 50 आइटम लौटाता है जब तक कि limit सेट न हो (max 200)।”
• “dueDate ISO 8601 date-time है।”
• “Write endpoints के लिए user token चाहिए।”

अंत में, तय करें कि आपका v1 scope क्या रहेगा। अगर आप अनिश्चित हैं तो v1 छोटा और स्पष्ट रखें (create, read, list, update status)। search, bulk updates और complex filters बाद में रखें ताकि अनुबंध भरोसेमंद बना रहे।

endpoints का वर्णन करने के लिए एक हल्का टेम्पलेट

Claude Code से स्पेक लिखवाने से पहले व्यवहार नोट्स को एक छोटे, पुनरावृत्त स्वरूप में लिखें। लक्ष्य यह है कि गलती से मॉडल के द्वारा gaps भरना मुश्किल हो।

एक अच्छा टेम्पलेट छोटा होना चाहिए ताकि आप वास्तव में उसका उपयोग करें, पर इतना सुसंगत कि दो लोग एक जैसे endpoint का वर्णन कर सकें। इसे API क्या करती है उस पर केंद्रित रखें, यह कैसे implement हुई है उस पर नहीं।

Endpoint behavior note template

Use one block per endpoint:

METHOD + PATH:
Purpose (1 sentence):
Auth:
Request:
- Query:
- Headers:
- Body example (JSON):
Responses:
- 200 OK example (JSON):
- 4xx example (status + JSON):
Edge cases:
Data types (human terms):

कम से कम एक concrete request और दो responses लिखें। status codes और realistic JSON bodies के साथ actual field names शामिल करें। यदि कोई फ़ील्ड optional है, तो ऐसा एक उदाहरण दिखाएँ जहाँ वह गायब है।

Edge cases को स्पष्ट रूप से बताइए। यही वे जगहें हैं जहाँ स्पेक बाद में चुपचाप गलत हो जाती है क्योंकि हर कोई कुछ अलग मान लेता है: empty results, invalid IDs (400 बनाम 404), duplicates (409 बनाम idempotent व्यवहार), validation failures, और pagination limits।

स्कीमा के बारे में सोचने से पहले plain शब्दों में data types नोट करें: strings बनाम numbers, date-time formats, booleans, और enums (उपलब्ध मानों की सूची)। इससे एक “सुंदर” स्कीमा बनना रोका जा सकता है जो वास्तविक payloads से मेल नहीं खाता।

Claude Code के साथ OpenAPI स्पेक ड्राफ्ट करें (ऐसा prompting काम करता है)

Claude Code सबसे अच्छा तब काम करता है जब आप उसे एक सावधान लेखक की तरह ट्रीट करें। उसे अपने behavior notes और OpenAPI के आकार के लिए सख्त नियम दें। यदि आप केवल कहेंगे "write an OpenAPI spec," तो आमतौर पर आपको अनुमान, inconsistent नामकरण, और missing error cases मिलेंगे।

अपने behavior notes पहले पेस्ट करें, फिर एक tight instruction block जोड़ें। एक व्यावहारिक prompt कुछ ऐसा दिखता है:

You are generating an OpenAPI 3.1 YAML spec.
Source of truth: the behavior notes below. Do not invent endpoints or fields.
If anything is unclear, list it under ASSUMPTIONS and leave TODO markers in the spec.

Requirements:
- Include: info, servers (placeholder), tags, paths, components/schemas, components/securitySchemes.
- For each operation: operationId, tags, summary, description, parameters, requestBody (when needed), responses.
- Model errors consistently with a reusable Error schema and reference it in 4xx/5xx responses.
- Keep naming consistent: PascalCase schema names, lowerCamelCase fields, stable operationId pattern.

Behavior notes:
[PASTE YOUR NOTES HERE]

Output only the OpenAPI YAML, then a short ASSUMPTIONS list.

ड्राफ्ट मिलने के बाद पहले ASSUMPTIONS स्कैन करें। यही वह जगह है जहाँ ईमानदारी जीती या हारती है। जो सही है उसे approve करें, जो गलत है उसे ठीक करें, और updated notes के साथ फिर रन करें।

नामकरण सुसंगति बनाए रखने के लिए upfront conventions बताएँ और उन पर टिके रहें। उदाहरण के लिए: एक stable operationId पैटर्न, noun-only tag names, singular schema names, एक साझा Error schema, और एक auth scheme नाम जो हर जगह उपयोग हो।

यदि आप Koder.ai जैसे vibe-coding workspace में काम करते हैं, तो early stage में YAML को एक वास्तविक फ़ाइल के रूप में सहेजना मदद करता है और छोटे diffs में iterate करना आसान होता है। आप देख सकते हैं कि कौन‑से बदलाव approved behavior decisions से आए और किन्हें मॉडल ने अनुमान लगाया।

स्पेक को रनिंग API से तुलना करने से पहले validate करें

Production से कुछ भी compare करने से पहले, सुनिश्चित करें कि OpenAPI फ़ाइल आंतरिक रूप से consistent है। यह wishful thinking और vague wording पकड़ने का सबसे तेज़ तरीका है।

प्रत्येक endpoint को ऐसे पढ़ें जैसे आप client developer हैं। ध्यान दें कि caller को क्या भेजना होगा और उन्हें क्या मिलने की उम्मीद हो सकती है।

एक व्यावहारिक review पास:

• Required vs optional: required फ़ील्ड्स को सही तरीके से मार्क करें और "सब कुछ optional" से बचें।
• Types और formats: UUIDs, emails, date-time, min/max values स्पष्ट रखें।
• Examples: हर endpoint के लिए कम-से-कम एक realistic request और response example जोड़ें, और examples को schemas के साथ align रखें।
• Status codes: अपने behavior notes के साथ align करें (create अक्सर 201 होता है, न कि 200)। 400 बनाम 422 चुनें और सुसंगत रहें।
• Auth: बताइए कि हर endpoint पर क्या जरूरी है और क्या roles access प्रभावित करते हैं।

Error responses को अतिरिक्त ध्यान दें। एक साझा shape चुनें और उसे हर जगह reuse करें। कुछ टीमें बहुत simple रखते हैं ({ error: string }), जबकि अन्य object उपयोग करती हैं ({ error: { code, message, details } })। दोनों काम कर सकते हैं, पर endpoints और examples में mixing न करें। अगर आप mix करेंगे, तो client code में special cases बढ़ेंगे।

एक तेज़ sanity scenario मदद करता है। यदि POST /tasks के लिए title चाहिए, तो स्कीमा में उसे required दिखाएँ, failure response वह दिखाए जो आप वास्तव में लौटाते हैं, और ऑपरेशन स्पष्ट रूप से बताए कि auth चाहिए या नहीं।

स्पेक की तुलना रनिंग API implementation से करें

जब स्पेक ऐसा लगे कि intended व्यवहार जैसा है, तो चलती हुई API को treat करें कि वह वही है जो क्लाइंट्स आज अनुभव करते हैं। लक्ष्य यह नहीं है कि स्पेक और कोड में “कौन सही है” की जंग जीतना, बल्कि फर्कों को जल्दी surface करना और हर एक पर स्पष्ट निर्णय लेना है।

पहले पास के लिए, real request/response samples सबसे सरल ऑप्शन होते हैं। logs और automated tests भी काम करते हैं अगर वे भरोसेमंद हों।

सामान्य mismatches पर ध्यान दें: एक जगह endpoint मौजूद है और दूसरी जगह नहीं, फ़ील्ड नाम या shape का फर्क, status code का अंतर (200 बनाम 201, 400 बनाम 422), undocumented behaviors (pagination, sorting, filtering), और auth के अंतर (स्पेक public कहता है पर कोड token मांगता है)।

उदाहरण: आपका OpenAPI कहता है कि POST /tasks 201 लौटाएगा {id,title}। आप रनिंग API को कॉल करते हैं और 200 मिलता है साथ में {id,title,createdAt}। यदि आप स्पेक से SDK जनरेट करते हैं तो यह “करीब है” पर्याप्त नहीं है।

कुछ भी एडिट करने से पहले तय करें कि कैसे conflict सुलझाएँ:

• यदि व्यवहार सही है पर undocumented है: स्पेक ठीक करें।
• यदि स्पेक सहमति वाला contract है: कोड ठीक करें।
• यदि दोनों गलत हैं: पहले intended behavior बदलें, फिर दोनों अपडेट करें।

हर बदलाव छोटा और review‑योग्य रखें: एक endpoint, एक response, या एक schema tweak। यह review और retest को आसान बनाता है।

contract से क्लाइंट और सर्वर validation उदाहरण बनाना

एक बार जब आपके पास एक भरोसेमंद स्पेक हो, तो उसे छोटे validation उदाहरणों में बदलें। यही चीज़ ड्रिफ्ट को वापस आने से रोकती है।

सर्वर‑साइड validation (गलत requests reject करना)

सर्वर पर validation का मतलब है कि यदि request contract से मेल नहीं खाती तो उसे जल्दी अस्वीकार करें और एक स्पष्ट error लौटाएँ। यह आपके डेटा की सुरक्षा करता है और bugs ढूँढना आसान बनाता है।

सर्वर validation उदाहरणों को केस के रूप में तीन हिस्सों में लिखना सरल है: input, expected output, और expected error (error code या message पैटर्न, न कि सटीक टेक्स्ट)।

उदाहरण (contract कहता है title required और 1 से 120 chars):

{
  "name": "Create task without title returns 400",
  "request": {"method": "POST", "path": "/tasks", "body": {"title": ""}},
  "expect": {"status": 400, "body": {"error": {"code": "VALIDATION_ERROR"}}}
}

क्लाइंट‑साइड validation (breaking changes जल्दी पकड़ना)

क्लाइंट पर validation का मकसद यह है कि सर्वर किसी अलग shape को लौटाने लगे तो टेस्ट पहले ही फ़ैल कर दें। यदि सर्वर किसी required फ़ील्ड को हटा दे या shape बदल दे तो आपकी टेस्ट्स उसे फ़्लैग करें।

क्लाइंट checks को उन चीजों पर केंद्रित रखें जिन पर आप सचमुच निर्भर करते हैं, जैसे “एक task में id, title, status होते हैं।” हर optional फ़ील्ड या exact ordering पर assert करने से बचें। आप ऐसे failures चाहते हैं जो breaking हों, न कि harmless additions के कारण हों।

कुछ दिशानिर्देश जो tests को पठनीय रखते हैं:

• presence और type चेक करें बजाय exact values के।
• केवल required फ़ील्ड्स को assert करें जब तक कोई optional फ़ील्ड आपकी feature के लिए critical न हो।
• errors के लिए status और error code चेक करें, पूरी messages नहीं।
• अतिरिक्त फ़ील्ड्स की अनुमति दें जब तक कि आपका contract उन्हें explicitly न रोके।

यदि आप Koder.ai के साथ बनाते हैं, तो आप इन example cases को OpenAPI फ़ाइल के पास रख सकते हैं और उन्हें उसी review का हिस्सा बना सकते हैं जब व्यवहार बदलता है।

उदाहरण परिदृश्य: सरल Tasks API end-to-end

मान लीजिए एक छोटा API है जिसमें तीन endpoints हैं: POST /tasks task बनाता है, GET /tasks tasks की सूची देता है, और GET /tasks/{id} एक task लौटाता है।

एक endpoint के लिए कुछ concrete examples लिखकर शुरू करें, जैसे आप किसी tester को समझा रहे हों।

POST /tasks के लिए intended व्यवहार हो सकता है:

• Success: { "title": "Buy milk" } भेजें और 201 प्राप्त करें जिसमें नया task object हो, जिसमें id, title, और done:false शामिल हों।
• Failure 1: {} भेजने पर 400 और { "error": "title is required" } लौटे।
• Failure 2: { "title": "x" } (बहुत छोटा) भेजने पर 422 और { "error": "title must be at least 3 characters" } लौटे।

जब Claude Code OpenAPI ड्राफ्ट करे, तो इस endpoint का स्निपेट स्कीमा, status codes, और realistic examples पकड़ना चाहिए:

paths:
  /tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              ok:
                value: { "title": "Buy milk" }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              examples:
                created:
                  value: { "id": "t_123", "title": "Buy milk", "done": false }
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingTitle:
                  value: { "error": "title is required" }
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tooShort:
                  value: { "error": "title must be at least 3 characters" }

एक सामान्य mismatch सूक्ष्म हो सकता है: रनिंग API 200 लौटाती है जबकि स्पेक 201 कहता है, या वह { "taskId": 123 } लौटाती है बजाय { "id": "t_123" } के। ये "लगभग वही" अंतर generated clients को तोड़ देते हैं।

इसे ठीक करने का तरीका: एक सच्चाई स्रोत चुनें। यदि intended behavior सही है, तो implementation को 201 और सहमत Task shape लौटाने के लिए बदलें। यदि production व्यवहार पहले से ही भरोसेमंद है, तो स्पेक (और behavior notes) को वास्तविकता के अनुसार अपडेट करें, फिर क्लाइंट्स को चौंकाने से रोकने के लिए missing validation और error responses जोड़ें।

अनुबंध को बेईमान बनाना वाले सामान्य गलतियाँ

एक अनुबंध तब बेईमान बन जाता है जब वह नियमों का वर्णन करना बंद कर देता है और आपके API ने किसी अच्छे दिन जो भी लौटाया, उसे बताने लग जाता है। एक सरल टेस्ट: क्या एक नई implementation इस स्पेक को पास कर सकती है बिना आज के quirks की नकल किए?

एक फंदा है overfitting। आप एक response पकड़ लेते हैं और उसे कानून बना देते हैं। उदाहरण: आपकी API फिलहाल हर task के लिए dueDate: null लौटाती है, इसलिए स्पेक कहता है कि फ़ील्ड हमेशा nullable है। पर असली नियम हो सकता है कि "जब status scheduled हो तब required है।" अनुबंध को नियम व्यक्त करना चाहिए, न कि केवल current dataset।

Errors वह जगह हैं जहाँ ईमानदारी अक्सर टूटती है। केवल success responses को spec करना आसान होता है क्योंकि वे साफ‑सुथरे दिखते हैं। लेकिन क्लाइंट्स को मूल बातें चाहिए: token missing पर 401, forbidden पर 403, unknown IDs पर 404, और एक consistent validation error (400 या 422)।

अन्य ऐसे पैटर्न जो समस्या पैदा करते हैं:

• नाम और types endpoints में अलग‑अलग हो जाना (taskId एक route में और id दूसरे में)
• examples schemas से विरोधाभासी होना (enum values नहीं मिलते, date-time examples ISO 8601 नहीं हैं)
• types को निर्णय से बचने के लिए widen कर दिया जाना (सब कुछ string बनाना, सब कुछ optional करना)
• स्पेक का भाषा marketing copy जैसी होना (“fast,” “secure”) बजाय testable contract के

एक अच्छा contract testable होना चाहिए। यदि आप स्पेक से एक failing test नहीं लिख सकते, तो यह अभी भी ईमानदार नहीं है।

शेयर या पब्लिश करने से पहले जल्दी वाले चेक्स

OpenAPI फ़ाइल किसी और टीम को देने से पहले एक तेज़ पास करें: “क्या कोई इसे बिना आपके दिमाग पढ़े उपयोग कर सकता है?”

Examples से शुरू करें। एक वैध स्पेक भी उपयोगी नहीं हो सकता अगर हर request और response abstract हों। हर ऑपरेशन के लिए कम-से-कम एक realistic request example और एक success response example रखें। Errors के लिए common failures पर एक example (auth, validation) आमतौर पर काफी होता है।

फिर consistency चेक करें। यदि एक endpoint { "error": "..." } लौटाता है और दूसरा { "message": "..." }, तो क्लाइंट्स में branching logic भर जाएगी। एक single error shape चुनें और उसे reuse करें, साथ ही predictable status codes रखें।

एक छोटा चेकलिस्ट:

• Required fields, formats (email, uuid, date-time), और enums explicit हों।
• Status codes similar endpoints में intentional और consistent हों।
• Error responses में schema और examples दोनों हों, सिर्फ status नहीं।
• आप हर endpoint पर 2-3 real calls दोबारा चलाएँ (tests, curl, Postman, या logs) और payloads को spec से तुलना करें।
• आप स्पेक से एक छोटा client call लिख सकते हैं बिना headers, field names, या nullability का अनुमान लगाए।

एक व्यावहारिक ट्रिक: एक endpoint चुनें, कल्पना करें कि आपने कभी API नहीं देखा, और जवाब दें “मैं क्या भेजूँगा, मुझे क्या वापस मिलेगा, और क्या टूटेगा?” अगर OpenAPI इसका साफ़ जवाब नहीं दे सकता, तो यह रेडी नहीं है।

अगले कदम: इसे आदत बनाइए (और बदलाव सुरक्षित रखें)

यह workflow तब लाभ देता है जब यह नियमित रूप से चलता है, न कि केवल release के समय। एक सरल नियम चुनें और उस पर टिके रहें: जब भी कोई endpoint बदलता है, इसे चलाएँ, और रिलीज़ से पहले फिर चलाएँ।

ownership को सरल रखें। जो व्यक्ति endpoint बदलता है वही behavior notes और spec ड्राफ्ट अपडेट करे। दूसरा व्यक्ति “spec बनाम implementation” diff की तरह review करे जैसे code review। QA या support टीमें अक्सर अच्छे reviewers होती हैं क्योंकि वे unclear responses और edge cases जल्दी पकड़ लेती हैं।

contract edits को कोड edits की तरह ट्रीट करें। यदि आप चैट‑ड्रिवन बिल्डर जैसे Koder.ai का उपयोग कर रहे हैं, तो risky edits से पहले snapshot लेना और आवश्यकता पड़ने पर rollback करना iteration को सुरक्षित रखता है। Koder.ai source code export करने का सपोर्ट भी देता है, जिससे spec और implementation को एक साथ अपने repo में रखना आसान होता है।

एक रूटीन जो आमतौर पर टीमों को धीमा किए बिना काम करती है:

• नया endpoint जोड़ते समय behavior notes लिखें
• merging से पहले OpenAPI फ़ाइल validate और contract tests चलाएँ
• रिलीज़ से पहले running API के साथ स्पेक की तुलना करें
• जोखिम भरे edits से पहले snapshot लें; अगर diff उलझा हुआ लगे तो rollback करें

अगला काम: कोई एक endpoint चुनें जो पहले से मौजूद है। 5-10 लाइन के behavior notes लिखें (inputs, outputs, error cases), उन नोट्स से एक ड्राफ्ट OpenAPI जेनरेट करें, उसे validate करें, फिर रनिंग implementation से तुलना करें। एक mismatch ठीक करें, रीटेस्ट करें, और दोहराएँ। एक endpoint के बाद आदत अक्सर रह जाती है।