इस पेज में एक तकनीकी लेखन प्रोजेक्ट की जानकारी है, जिसे दस्तावेज़ के Google सीज़न के लिए स्वीकार किया जाता है.
प्रोजेक्ट की खास जानकारी
- ओपन सोर्स संगठन:
- OWASP फ़ाउंडेशन
- टेक्निकल राइटर:
- sshniro
- प्रोजेक्ट का नाम:
- ZAP API के दस्तावेज़ को बेहतर बनाना
- प्रोजेक्ट की अवधि:
- स्टैंडर्ड लंबाई (तीन महीने)
प्रोजेक्ट का विवरण
ZAP में एक बहुत ही बेहतरीन एपीआई है, जिसकी मदद से हम डेस्कटॉप इंटरफ़ेस से लगभग सभी काम कर सकते हैं. हालांकि, इस एपीआई का बेहतर तरीके से इस्तेमाल करने के लिए, यूज़र इंटरफ़ेस (यूआई) की अच्छी जानकारी होना ज़रूरी है. इसकी वजह यह है कि ज़्यादातर एपीआई, ZA प्रॉक्सी के यूज़र इंटरफ़ेस से सीधे तौर पर जुड़े होते हैं. एपीआई को आज़माते समय, इस समस्या को हल करने में, एपीआई और इस्तेमाल/ इस्तेमाल के उदाहरण के बारे में अच्छी तरह से जानकारी देने वाले दस्तावेज़ मददगार हो सकते हैं.
फ़िलहाल, एपीआई दस्तावेज़ अपने-आप जनरेट होते हैं. इनमें शामिल पैरामीटर के बारे में बहुत कम जानकारी मिलती है. साथ ही, कम्यूनिटी को एपीआई दस्तावेज़ में योगदान देने का कम मौका मिलता है. इसके अलावा, ZAP में इस्तेमाल किया जाने वाला वेब-आधारित यूज़र इंटरफ़ेस (डेस्कटॉप वर्शन), एपीआई को कॉल करने के लिए अपने-आप जनरेट हुई सूची का इस्तेमाल करता है. वेब पर आधारित एपीआई को कॉल करने वाले इस यूज़र इंटरफ़ेस (यूआई) में, एपीआई का इस्तेमाल करने के तरीके और एपीआई को कॉल करने पर मिलने वाले नतीजों (उदाहरण के लिए, एपीआई के नतीजे) के बारे में बहुत कम जानकारी मिलती है. इसलिए, इस प्रस्ताव में मैं एपीआई से जुड़े दस्तावेज़ तैयार करने के एक नए तरीके का सुझाव दे रहा हूं.
इसका मकसद, Open API 3 स्पेसिफ़िकेशन के साथ एपीआई दस्तावेज़ों को फिर से बनाना है. Open API, डेवलपर, टेस्टर, और डेवलपर को एपीआई बनाने, उनका रखरखाव करने, और उनकी जांच करने के लिए एक सामान्य फ़्रेमवर्क उपलब्ध कराता है. ZAP के लिए उपलब्ध Open API की पूरी जानकारी का इस्तेमाल, स्वैगर फ़ाइलों को अपने-आप जनरेट करने के लिए किया जा सकता है. Swagger फ़ाइलों को ZAP के वेब ऐप्लिकेशन (डेस्कटॉप ऐप्लिकेशन) यूज़र इंटरफ़ेस (यूआई) में इंटिग्रेट किया जा सकता है, ताकि उपयोगकर्ताओं को बेहतर एपीआई टेस्टिंग क्लाइंट दिया जा सके.
एपीआई दस्तावेज़ के अलावा, मुझे Markdown फ़ॉर्मैट में एपीआई दस्तावेज़ जनरेट करने के लिए, swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) कन्वर्टर का इस्तेमाल करना है. इस तरीके (swagger-converter) से, अप-टू-डेट RESTful API दस्तावेज़ जनरेट करना आसान हो जाता है. इसके लिए, Swagger की मदद से अपने-आप जनरेट हुए एपीआई दस्तावेज़ को, हाथ से लिखे गए दस्तावेज़ के साथ जोड़ा जाता है. नतीजे, GitHub के एपीआई दस्तावेज़ से मिलते-जुलते होंगे. (https://developer.github.com/v3/). इस हस्तलिखित दस्तावेज़ में, एपीआई का इस्तेमाल करके कोई काम करने का तरीका बताने वाले हाई-लेवल दस्तावेज़ होंगे. उदाहरण के लिए, स्पाइडर एपीआई स्कैन एक लंबा टास्क है. साथ ही, एपीआई की स्थिति जानने के लिए, उपयोगकर्ता को एपीआई को लगातार पोल करना चाहिए. इसलिए, ये हाई-लेवल दस्तावेज़ इस पर चर्चा करेंगे कि कोई कार्रवाई करने के लिए किन एपीआई का इस्तेमाल किया जाए. साथ ही, आगे पढ़ने के लिए अपने-आप जनरेट हुए स्वैगर दस्तावेज़ों पर ले जाया जाएगा.
ZA प्रॉक्सी में कुल 380 से ज़्यादा एपीआई लागू किए गए हैं. शुरुआत में, मेरा सुझाव है कि सभी एपीआई के बारे में जानकारी, पैरामीटर, और एपीआई के काम करने और काम न करने के रिस्पॉन्स के बारे में जानकारी के साथ दस्तावेज़ बनाए जाएं. पहले से ही एक सैंपल पीओसी किया जा चुका है. ज़्यादा जानकारी के लिए, लिंक किए गए प्रस्ताव को देखें.
तीन महीने की इस अवधि को तीन चरणों में बांटा जाएगा. पहले चरण में, ऐक्टिव स्कैन और मुख्य एपीआई (150 से ज़्यादा) के लिए, ओपन एपीआई स्पेसिफ़िकेशन बनाए जाएंगे. साथ ही, खास टास्क करने के लिए एपीआई का इस्तेमाल करने के तरीके के बारे में, इस्तेमाल के उदाहरणों वाले दस्तावेज़/ हाई-लेवल दस्तावेज़ भी बनाए जाएंगे. मैन्युअल तरीके से काम करने की ज़रूरत न पड़े, इसके लिए इसे वर्शन में बांटा जा सकता है और अपने-आप जनरेट किया जा सकता है. साथ ही, Markdown फ़ाइलों को वेबपेज के तौर पर होस्ट किया जा सकता है या PDF के तौर पर एक्सपोर्ट किया जा सकता है.
दूसरे चरण में, स्पाइडर, अपने-आप अपडेट होने की सुविधा, कॉन्टेक्स्ट, स्टेटस, और Search API के दस्तावेज़ तैयार करने के बारे में जानकारी दी जाएगी. साथ ही, Markdown फ़ाइलों की मदद से इस्तेमाल के उदाहरण वाले लेख तैयार किए जाएंगे.
आखिरी चरण में, दस्तावेज़ में शामिल नहीं किए गए बाकी एपीआई और उनके काम के इस्तेमाल के उदाहरणों को शामिल किया जाएगा. आखिरी महीने में, हम उन इस्तेमाल के उदाहरणों को भी कवर करने वाले हैं जिनमें किसी टास्क को पूरा करने के लिए, एक से ज़्यादा एपीआई कॉम्पोनेंट को कॉल करने की ज़रूरत होती है.