how create api documentation postman
यह ट्यूटोरियल बताता है कि पोस्टमैन द्वारा प्रदान की गई एपीआई दस्तावेज़ीकरण सहायता का उपयोग करके न्यूनतम प्रयास के साथ अच्छी दिखने वाली, आकर्षक प्रलेखन कैसे बनाएं:
किसी भी एपीआई के लिए, चाहे आंतरिक या सार्वजनिक-सामना, प्रलेखन इसकी सफलता के लिए सबसे आवश्यक सामग्री में से एक है।
इसका मुख्य कारण है, प्रलेखन वह तरीका है जिससे आप अपने उपयोगकर्ताओं के साथ संवाद करते हैं।
- आपके API का उपयोग कैसे किया जाना चाहिए?
- सभी स्थिति कोड समर्थित हैं?
- त्रुटि कोड क्या हैं?
- सभी विधि प्रकार क्या हैं?
वांछित आवश्यकता के लिए एपीआई का उपयोग करने या कार्यान्वित करने के लिए यह सभी जानकारी आवश्यक है।
=> यहाँ सरल डाकिया प्रशिक्षण श्रृंखला देखें।
विंडोज़ 10 के लिए सबसे अच्छा जंक फाइल क्लीनर
डाकिया प्रलेखन पद्धति का उपयोग करने के लिए एक आसान प्रदान करता है और बुनियादी प्रलेखन के लिए, यह डाकिया संग्रह के माध्यम से एक बटन पर क्लिक करने के रूप में सरल है और आप अपने एपीआई प्रलेखन के लिए सार्वजनिक URL प्राप्त कर सकते हैं।
आप क्या सीखेंगे:
डाकिया में एपीआई प्रलेखन बनाना
प्रलेखन सुविधाएँ
डाकिया प्रलेखन जनरेटर की मुख्य विशेषताओं में शामिल हैं:
- यह मार्कडाउन सिंटैक्स का समर्थन करता है। मार्कडाउन जेनेरिक डॉक्यूमेंटेशन सिंटैक्स है, जिसे आपको आमतौर पर किसी भी गिथब प्रोजेक्ट पर ध्यान देना चाहिए। यह स्टाइलिंग और टेक्स्ट फ़ॉर्मेटिंग को अधिक परिचित और आसान बनाने की अनुमति देता है।
- प्रलेखन बनाने के लिए कोई विशिष्ट वाक्यविन्यास / आवश्यकताएं नहीं। अनुरोध और संग्रह जानकारी का उपयोग प्रलेखन उत्पन्न करने के लिए सबसे अच्छे तरीके से किया जाता है।
- इसे एक सार्वजनिक URL या एक कस्टम डोमेन (एंटरप्राइज़ उपयोगकर्ताओं के लिए) में प्रकाशित किया जा सकता है।
- C #, PHP, Ruby, Python, Node, आदि जैसी विभिन्न भाषाओं में API को कॉल करने के लिए कोड स्निपेट्स बनाता है।
प्रलेखन बनाना
डाकिया दस्तावेज़ जनरेटर संग्रह, फ़ोल्डर और व्यक्तिगत अनुरोध विवरण को संदर्भित करता है और संग्रह के लिए दस्तावेज बनाते या उत्पन्न करते समय उन्हें टकराता है।
यह हेडर, क्वेरी स्ट्रिंग पैरामीटर, फॉर्म पैरामीटर जैसे विभिन्न अनुरोध मापदंडों का उपयोग करता है और अनुरोध प्रलेखन में इन मूल्यों के उपयोग को इंगित करता है।
यहाँ एक वीडियो ट्यूटोरियल है:
आइए हमारे अन्य लेखों के समान ही परीक्षण एपीआई का उपयोग करके 3 अनुरोधों के साथ एक मूल संग्रह बनाएं। हम संग्रह के विवरण के साथ-साथ व्यक्तिगत अनुरोधों के लिए कुछ जानकारी जोड़ेंगे और कुछ उदाहरण अनुरोध और प्रतिक्रियाएं भी बनाएंगे, जिन्हें प्रलेखन बनाते समय भी कैप्चर किया जाएगा।
अनुरोधों के बारे में बुनियादी जानकारी जोड़ने और फिर दस्तावेज़ बनाने के लिए नीचे दिए गए चरणों का पालन करें।
# 1) 3 अनुरोधों के साथ एक संग्रह बनाएं यानी रजिस्टर उपयोगकर्ता, लॉगिन उपयोगकर्ता और उपयोगकर्ता प्राप्त करें (देखें) यहां अनुरोध पेलोड और एपीआई यूआरएल के लिए)।
#दो) अब मार्कडाउन फॉर्मेट में कुछ जानकारी को कलेक्शन में जोड़ें। मार्कडाउन एक मानक प्रारूप है जिसका उपयोग जीथब में लगभग सभी प्रलेखन के लिए किया जाता है (मार्कडाउन संदर्भ के बारे में अधिक जानकारी के लिए यहां ) का है।
हम नीचे दिए गए निशान के प्रारूप में संग्रह विवरण में कुछ जानकारी जोड़ेंगे।
यह देखने के लिए कि मार्कडाउन कैसा दिखता है, ओपन-सोर्स वेब पोर्टल देखें यहां।
# 3) अब हम संग्रह में अलग-अलग अनुरोधों के विवरण जोड़ देंगे। संग्रह के समान, मार्कडाउन प्रारूप अनुरोध विवरण के लिए भी समर्थित है (मार्कडाउन गाइड पर अधिक विस्तृत जानकारी के लिए, देखें यहां ) का है।
आइए रजिस्टर उपयोगकर्ता समापन बिंदु के लिए अनुरोधों में से एक का एक नमूना देखें (इसे अन्य अनुरोधों पर भी लागू किया जा सकता है)।
मार्कडाउन टेक्स्ट:
API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status codeमार्कडाउन पूर्वावलोकन:
# 4) सभी एपीआई एंडपॉइंट्स के लिए, एक उदाहरण को कैप्चर या सेव करें, जो डॉक्यूमेंटेशन जनरेटर द्वारा उपयोग किया जाएगा।
एक उदाहरण और कुछ नहीं बल्कि एपीआई अनुरोध के लिए एक नमूना अनुरोध-प्रतिक्रिया है। एक उदाहरण के रूप में प्रतिक्रिया को सहेजना प्रलेखन जनरेटर को दस्तावेज के एक हिस्से के रूप में इसे पकड़ने में सक्षम बनाता है।
एक उदाहरण को बचाने के लिए, हिट करें 'भेजें' बटन अनुरोध को निष्पादित करने के लिए और प्रतिक्रिया टैब पर, क्लिक करें उत्तर सहेजें -> उदाहरण के रूप में सहेजें ।
एक बार उदाहरण सहेजे जाने के बाद, यह संग्रह के लिए जारी रहता है और भविष्य में कभी भी ए के माध्यम से एक्सेस किया जा सकता है उदाहरण लिंक बिल्डर में लिंक।
# 5) एक बार उपरोक्त सभी जानकारी जुड़ जाने के बाद, आइए देखें कि दस्तावेज़ पूर्वावलोकन कैसे बनाया जाए।
संग्रह विकल्प खोलें और क्लिक करें “ डॉक्स प्रकाशित करें ”।
ध्यान दें: यहां ध्यान देने वाली एक महत्वपूर्ण बात यह है कि पोस्टमैन के साथ केवल पंजीकृत उपयोगकर्ता ही पोस्टमैन पर पब्लिश डॉक्स फीचर का उपयोग कर पाएंगे। पंजीकरण मुफ्त है, लेकिन आपके ईमेल खाते के माध्यम से किया जाना चाहिए। अन्य क्षमताएं / विशेषताएं हैं जैसे संग्रह और कार्यक्षेत्र साझा करना, मॉनिटर बनाना आदि, जो पंजीकृत खातों में जुड़ जाते हैं।
# 6) एक बार ' डॉक्स प्रकाशित करें 'निष्पादित किया जाता है, एक ब्राउज़र टैब पोस्टमैन संग्रह विवरण के साथ खोला जाता है (आंतरिक रूप से पोस्टमैन इस संग्रह को अपने स्वयं के सर्वर के साथ-साथ उपयोगकर्ता की स्थानीय फ़ाइल सिस्टम के साथ होस्ट करता है)।
पर क्लिक करें 'पूर्वावलोकन' प्रकाशित होने से पहले प्रलेखन देखने के लिए।
' संग्रह प्रकाशित करें “लिंक सार्वजनिक रूप से सुलभ URL पर प्रलेखन प्रकाशित करेगा। आम तौर पर सार्वजनिक URL को प्रकाशित करने के लिए संवेदनशील प्राधिकरण जानकारी वाले एपीआई को प्रकाशित करने की अनुशंसा नहीं की जाती है। पोस्टमैन के उद्यम खातों के साथ कस्टम डोमेन का उपयोग करके ऐसे एपीआई प्रकाशित किए जा सकते हैं।
# 7) आइए देखें कि प्रलेखन पूर्वावलोकन कैसा दिखता है। 'पर क्लिक करें दस्तावेज़ीकरण का पूर्वावलोकन करें पोस्टमैन के सर्वर पर होस्ट किए गए पूर्वावलोकन मोड में दस्तावेज़ खोलता है। आइए देखें कि दस्तावेज़ में विभिन्न विवरणों को क्या पकड़ा गया है (जैसा कि हमने विभिन्न स्थानों पर कॉन्फ़िगर किया है। उदाहरण के लिए , संग्रह विवरण, अनुरोध विवरण और उदाहरण)।
उपरोक्त 2 स्क्रीनशॉट में, आप देख सकते हैं कि संग्रह और अनुरोध के विवरण में जोड़ी गई सभी जानकारी को दस्तावेज़ीकरण पूर्वावलोकन में मार्कडाउन शैली में कैप्चर किया गया है।
उदाहरणों के साथ यूनिक्स में कमांड खोजें
इसके अलावा, डिफ़ॉल्ट रूप से प्रलेखन हाइलाइट किए गए के रूप में भाषा बाइंडिंग प्रदान करता है और यह किसी को सीधे सूचीबद्ध भाषा में एपीआई अनुरोध करने के इच्छुक व्यक्ति के लिए बहुत आसान बनाता है।
# 8) यह आपको बहुत ही मूल स्टाइल संशोधन करने की अनुमति देता है जैसे कि बैकग्राउंड कलर बदलना, हेडर टेम्प्लेट का बैकग्राउंड और फोरग्राउंड कलर बदलना आदि, लेकिन कुल मिलाकर, डिफॉल्ट व्यू अपने आप में डॉक्यूमेंटेशन के बहुत अच्छे सेट को प्रकाशित करने के लिए पर्याप्त है। एपीआई के बारे में महत्वपूर्ण जानकारी।
निष्कर्ष
इस ट्यूटोरियल में, हम डाकिया द्वारा उपलब्ध कराई गई एपीआई प्रलेखन सहायता से गुजरे, जिसका उपयोग करके हम कम से कम प्रयास के साथ एक अच्छी दिखने वाली, स्टाइल वाले दस्तावेज बना सकते हैं।
यह बहुत सारे अच्छे टेम्पलेट्स और उपयोगकर्ता-परिभाषित स्टाइलिंग की अनुमति देता है जो जेनरेट किए गए डॉक्स पर लागू किए जा सकते हैं और साथ ही एक सार्वजनिक URL पर प्रलेखन प्रकाशित करने की अनुमति देता है।
निजी एपीआई एंडपॉइंट के लिए, एक कस्टम डोमेन के लिए दस्तावेज़ प्रकाशित करने का भी प्रावधान है जो एंटरप्राइज़ खातों या उपयोगकर्ताओं के लिए कॉन्फ़िगर किया जा सकता है।
आगे पढ़ना = >> पैक्ट ब्रोकर को पैक्ट कॉन्ट्रैक्ट कैसे प्रकाशित करें
=> स्क्रैच से पोस्टमैन जानने के लिए यहां जाएं
अनुशंसित पाठ
- पोस्टमैन ट्यूटोरियल: एपीआई टेस्ट पोस्टमैन का उपयोग करना
- डाकिया पूर्व अनुरोध और पोस्ट अनुरोध लिपियों का उपयोग कैसे और कब करें?
- विभिन्न एपीआई प्रारूपों के परीक्षण के लिए पोस्टमैन का उपयोग कैसे करें?
- पोस्टमैन में न्यूमैन के साथ कमांड लाइन एकीकरण का उपयोग कैसे करें?
- बाकी एपीआई ट्यूटोरियल: बाकी एपीआई वास्तुकला और बाधाओं
- अटकलें फ़ीचर फ़ाइलों के लिए अचार के साथ जीवित प्रलेखन उत्पन्न करें
- डाकिया में दावे के साथ स्वचालित प्रतिक्रिया प्रतिक्रिया
- बाकी एपीआई प्रतिक्रिया कोड और बाकी अनुरोधों के प्रकार