मेरी सिफारिश [स्रोत कोड से दस्तावेज़] जेनरेटर पर बहुत अधिक भरोसा नहीं करना होगा। मुझे लगता है कि दस्तावेज़ के दर्शक आखिर में इंसान हैं और उन्हें WADL और मशीन जेनरेट की गई फ़ाइलों के मुकाबले बहुत कुछ चाहिए। उपकरण की सहायता करने के लिए आपको उपकरण की idosyncracies मास्टर करने के लिए समय और प्रयास निवेश करना है।
इसके अलावा, एक वास्तविक व्यावहारिक सीमा है कि एपीआई के स्रोत कोड के अंदर कितना शामिल किया जा सकता है। केवल पैरामीटर नामों और प्रकारों को दस्तावेज करना बहुत मदद नहीं करेगा (और पूर्ण) और स्रोत कोड के अंदर नमूना अनुरोध और प्रतिक्रिया जोड़ना सादा बुरा लगता है (हालांकि अंतिम उपयोगकर्ताओं के लिए आवश्यक जानकारी)। एक और कारण बस सौंदर्यशास्त्र हो सकता है।
ट्विटर भी दस्तावेज़ों को हाथ से रखता है और यह बहुत कुछ बता रहा है। आईएमएचओ, सबसे अच्छा विकल्प कुछ मानव अनुकूल प्रारूप में दस्तावेज बनाए रखना और उस से एचटीएमएल/पीडीएफ आदि उत्पन्न करना होगा।
बेशर्म प्लग
https://github.com/rjha/restdoc
यह बहुत ही सरल PHP स्क्रिप्ट कि YAML परिभाषा फ़ाइलों से पढ़ सकते हैं और एपीआई HTML बनाने का सिर्फ जोड़ी है। EBay प्रकार के विशाल एपीआई के लिए अच्छी तरह से स्केल नहीं हो सकता है लेकिन सरल एपीआई दस्तावेज आवश्यकताओं के लिए यह जाने का एक तरीका हो सकता है।
एक और अच्छा सवाल और उत्तर जो इस साइट के दायरे में फिट नहीं है, क्योंकि यह संकुचित रूप से कल्पना की गई है। –