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