एपीआई प्रलेखन: ओपनएपीआई, स्वैगर, पोस्टमैन

टीएल; डीआर

OpenAPI - सत्य का स्रोत: अनुबंध → SDK → मोकी → परीक्षण → पोर्टल।

स्वैगर यूआई/रेडोक - पढ़ ने योग्य शोकेस; पोस्टमैन निष्पादन योग्य स्क्रिप्ट।

हम लिंटर्स, ब्रेकिंग-चेक, उदाहरण और त्रुटि योजनाओं में सिल देते हैं, एसडीके और मॉक सर्वर उत्पन्न करते हैं, एक वर्शन देव पोर्टल और "सनसेट" प्रकाशित करते हैं।

1) लक्ष्य और सिद्धांत

अनुबंध एक (OpenAPI)। बाकी सब कुछ उत्पन्न होता है।

प्रलेखन निष्पादन योग्य है: पोस्टमैन/सीएलआई में नमूना अनुरोधों का परीक्षण किया जाता है।

डिफ़ॉल्ट सुरक्षा: त्रुटि योजना, सीमा, सत्यापन.

वर्शनिंग और जीवन चक्र: 'v1 '/' v2', Deprecation/Sunset, changelog।

2) OpenAPI संरचना (न्यूनतम कंकाल)

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• स्कीमा/प्रतिक्रियाओं/मापदंडों/ निकायों को 'components' में विघटित करें।
• योजनाओं ( ) का वर्णन करें और 'पथ '/' वैश्विक' स्तर पर लागू करें।

3) त्रुटि मानक और मेटाडेटा

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

हमेशा दस्तावेज़ 429 (दर सीमा), 401/403, और हेडर 'एक्स-रेटलिमिट-', 'रेट्री-आफ्टर'।

4) उदाहरण: अनुरोध/प्रतिक्रिया, कर्ल और एसडीके

प्रत्येक समापन बिंदु के लिए: न्यूनतम और विस्तारित उ

ओपनएपीआई से कर्ल और कोड स्निपेट (JS/Python/Go) उत्पन्न करें; अपने हाथों से न लिखें।

वास्तविक मान लागू करें: यूयूआईडी, आईएसओ-तिथि, "माइनर" (सेंट) में रकम।

विस्तारित प्रतिक्रिया उदाह

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5) स्वैगर यूआई/रेडोक - कैसे पोस्ट करें

1. स्वैगर यूआई (इंटरैक्टिव, ट्राई-इट-आउट),

2. Redoc (पढ़ने योग्य लंबे पृष्ठ)।

शामिल करें: डार्क थीम, खोज, संस्करण चयनकर्ता ('v1', 'v2'), Deprecation बैनर।

उत्पादन डोमेन के लिए "इसे बाहर कोशिश करें" छुपाएँ, सैंडबॉक्स पर अनुमति दें।

6) पोस्टमैन संग्रह: लाइव स्क्रिप्ट

OpenAPI से संग्रह को स्वचालित करें और पर्यावरण चर का समर्थन करें ('{BaseUrl}}', '{{AccesTocen}}')।

दिखावा (एक टोकन प्राप्त करना) और पोस्ट-टेस्ट (दावा स्थिति/स्कीमा) जोड़ें।

फ़ोल्डर में तोड़ें: औथ, पेमेंट, पेआउट, वेबहूक।

महत्वपूर्ण मार्गों के लिए निर्यात मॉनिटर (अनुसूचित

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7) मोकी और सैंडबॉक्स

OpenAPI से एक मॉक सर्वर उत्पन्न करें (उदाहरण/' उदाहरण '/' उदाहरण ').

Mocs की सीमाओं को इंगित करें: पहचान, देरी, यादृच्छिक त्रुटियां (UAT के लिए)।

दस्तावेज़ सैंडबॉक्स बनाम प्रॉड अंतर (सीमा, डेटा, देरी)।

8) एसडीके ऑटोजेनरेशन

OpenAPI से, आधिकारिक SDK (टाइपस्क्रिप्ट, पायथन, गो) उत्पन्न करें।

SDK रिलीज़ पॉलिसी = SemVer, API संस्करण मैपिंग।

README SDK में: प्रमाणीकरण, रिट्रे, आइडेम्पोटेंसी, 429/Retry-After प्रोसेसिंग।

9) लिंटिंग, ब्रेकेज चेक और सीआई

लिंटर्स: वर्णक्रमीय (शैली/एंटी-पैटर्न), ओपनपी-डिफ़ (ब्रेकिंग-चेक)।

• सर्किट सत्यापन,
• लिंटर,
• आईओसी सर्वर के खिलाफ अनुबंध परीक्षण,
• स्वैगर/रेडोक/संग्रह विधानसभा,
• पोर्टल पर प्रकाशन (staging→prod),
• मूल्यह्रास/सूर्यास्त चेतावनी।

10) वर्शनिंग, मूल्यह्रास, सूर्यास्त

यूआरआई ('/v1 ') और' जानकारी में संस्करण। संस्करण '।

मूल्यह्रास झंडे: 'Deprecation: true', 'Sunset: ', 'Link: ' हेडर।

पोर्टल में - डिस्कनेक्शन से पहले एक बैनर और एक टाइमर; V1 के लिए पोस्टमैन संग्रह जमे हुए हैं (केवल बग फिक्स)।

11) गोदी में सुरक्षा और गोपनीयता

रहस्य, आंतरिक यूआरएल, वास्तविक पैन/पीआईआई पोस्ट न करें।

संवेदनशील क्षेत्रों के लिए - मास्किंग और स्टब उदा

स्वैगर "इसे आज़माएं" - केवल सैंडबॉक्स के लिए, दर-सीमा के साथ।

स्पष्ट रूप से वर्णन करें OAuth2/OIDC, HMAC (वेबहूक के लिए) और mTLS (यदि आवश्यक हो)।

12) स्टाइल गाइड अनुबंध

संसाधन बहुवचन: '/भुगतान ', '/भुगतान'।

पहचानकर्ता: 'भुगतान _',' पो _', UUIDv4 या ksuid।

दिनांक - UTC ISO-8601; पैसा - 'राशि _ माइनर + मुद्रा'।

पृष्ठभूमि - संकेतक आधारित ('? कर्सर = & सीमा = '), स्थिर छंटाई।

उत्परिवर्तन के लिए पहचान - 'Idempotency-Key'।

सूचियों के लिए स्थिर वस्तु 'मेटा' और 'लिंक'।

13) गोदी का "वेबहूक" खंड

घटना लिफाफे, HMAC हस्ताक्षर, समय विंडो, रिट्रे, प्रतिक्रिया कोड के साथ अलग अनुभाग।

स्थानीय हस्ताक्षर सत्यापन के लिए नमूना घटना निकाय और पोस्टमैन संग्रह

रीप्ले/डीएलक्यू एंडपॉइंट और यूएटी चेकलिस्ट।

14) देव पोर्टल: भूमिकाएँ और प्रकाशन

अनुभाग: अवलोकन, प्रारंभ होना, प्रमाणीकरण, एंडपॉइंट, उदाहरण, वेबहूक, एसडीके, प्रतिबंध, चेंजलॉग।

भूमिकाएँ: स्टीवर्ड एपीआई (मानक), डोमेन मालिक (सामग्री), टेक राइटर (संपादन), डेवरेल (पोर्टल/समुदाय)।

फ़ीचर: स्कीमा फ़ील्ड के माध्यम से खोजें, नमूने कॉपी करें, "अनुरोध एकत्र करें" → पोस्टमैन।

15) चेकलिस्ट

• OpenAPI वैध है; त्रुटियों के बिना लिंटर।
• उदाहरण 200/4xx/429/5xx को कवर करते हैं।
• सुरक्षा: वर्णित योजनाएं, कोई रहस्य नहीं।
• गठित स्वैगर/रेडोक और पोस्टमैन (prod/sandbox)।
• एसडीके उत्पन्न और प्रकाशित।
• अपडेटेड चेंजलॉग और संस्करण चयनकर्ता।

• Deprecation/Sunset हेडर शामिल हैं।
• पोर्टल में बैनर, भागीदारों को पत्र।
• लिगेसी कॉल मैट्रिक्स लक्ष्य के लिए गिरते हैं।

16) एंटी-पैटर्न

सत्य के डुप्लिकेट स्रोत (विकी ≠ OpenAPI)।

पोस्टमैन में चल रहे बिना "आंख से" के उदाहरण।

एकल त्रुटि प्रारूप का अभाव।

यूआरआई/डोमेन के बजाय "क्वेरी पैरामीटर में" संस्करण।

भोजन तक पहुंच और कोई सीमा नहीं के साथ स्वैगर।

असंगत पृष्ठभूमि और प्रमाणीकरण योजनाएं।

17) स्वचालन के मिनी स्निपेट्स

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18) स्थानीयकरण और उपलब्धता

व्यक्तिगत 'info। description_' या दो पोर्टल असेंबली (EN/RU)।

शब्दावली शब्द (KYC/AML, भुगतान, पहचान)।

कंट्रास्ट, कीबोर्ड नेविगेशन, डार्क थीम।

सारांश

प्रलेखन की एक पाइपलाइन को इकट्ठा करें: एक एकल ओपनएपीआई अनुबंध - लिंटर्स और ब्रेकिंग-चेक स्वैगर/रेडॉक शोकेस पोस्टमैन संग्रह और एक मॉक सर्वर एसडीके एक संस्करण पोर्टल और सनसेट। नियमित उदाहरण, एक एकल त्रुटि प्रारूप, और मजबूत प्रमाणीकरण शेल्फ पर पीडीएफ से प्रलेखन को एक काम करने वाले एकीकरण उपकरण में बदल देगा, भागीदारों को तेज करेगा और समर्थन लागत को कम करेगा।