Fosrestbundle: मार्गों से बाहर आरईएसटी एपीआई दस्तावेज पीढ़ी

कुछ प्रेरणा के लिए http://getfrapi.com/ स्क्रीनकास्ट देखें।

मैंने इसे पहले ही देख लिया है। लेकिन मुझे उनके एहसास में बहुत सी चीजें पसंद नहीं हैं। सबसे पहले, उनका REST RESTful नहीं है :-D

"प्रेरणा" और मैं उनके आराम के बारे में नहीं बल्कि उनके डॉक्टर (और परीक्षण) पीढ़ी के बारे में बात कर रहा था :)

मुझे व्यक्तिगत रूप से यह पसंद नहीं है, लेकिन क्या हम WADL प्रारूप में प्रलेखन की पीढ़ी पर चर्चा कर सकते हैं?

http://www.w3.org/Submission/wadl/

मुझे आश्चर्य है कि पीढ़ी से बेहतर दिशा कुछ दृश्य सहायकों को प्रदान करना होगा जो दस्तावेज़ीकरण नियंत्रकों/विचारों के त्वरित निर्माण की अनुमति देते हैं। यह केवल एक संरचना बनाने से बेहतर लगता है और यह अधिक एक्स्टेंसिबल/रखरखाव योग्य होगा। दूसरे शब्दों में, मुझे लगता है कि एपीआई डॉक्स बनाना FRAPI के उपयोग के मामले (एक ऐप में ड्रॉप) के लिए बहुत अच्छा काम करता है, लेकिन सवाल है कि क्या हमें इस सुविधा की आवश्यकता है "जैसा है" या यदि यह समझ में आता है।

क्या हम ग्राहकों के लिए दस्तावेज़ीकरण के बारे में बात कर रहे हैं?

दिमाग में, यही वह है जो आरईएसटी से बचने की कोशिश करता है :)

ओडिनो: ज़रूर। लेकिन तथ्य यह है कि अगर आप HATEAOS का पालन करते हैं तो भी आपको हेडर का निरीक्षण करने की आवश्यकता है। जबकि आपको अलग-अलग स्थिति कोड की अपेक्षा करने के बारे में पता होना चाहिए, फिर भी यह जानना अच्छा है कि कौन से स्थिति कोड "अधिक संभावना" हैं। यह एपीआई की आकस्मिक समीक्षा के लिए बस अच्छा है।

एक और विषय जिसे नजरअंदाज किया जाना चाहिए: कुछ ग्राहक पेड़ों को मारना पसंद करते हैं और यह अच्छा है कि कागज के इस पृष्ठ को भरने में बहुत समय बर्बाद न करना पड़े :)

सहमत हैं, केवल एक चीज जिससे हमें बचना चाहिए, वह है जेनरेट किए गए दस्तावेज़ीकरण पर बहुत अधिक भरोसा करना, अन्यथा हम डब्लूएसडीएल को दोहराएंगे

पेड़-हत्यारों के लिए अंगूठे नीचे :)

जहां तक ​​​​मुझे पता है, सच्चे आरईएसटी एपीआई दस्तावेज़ मीडिया प्रकारों और उनके संबंधों को परिभाषित करने के बारे में हैं, यूआरएल नहीं। जैसे http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

लेकिन साधारण HTTP एपीआई के लिए, जो कि 80% वेब प्रोजेक्ट्स के लिए होगा, यह सुविधा अभी भी उपयोगी होगी।

हां व्लादर, यूआरआई टेम्पलेट्स स्पष्ट रूप से बुरे हैं। लेकिन अगर हमें एक आरईएसटी बंडल विकसित करने की ज़रूरत है तो हमें उन सिद्धांतों का पालन करना चाहिए।

एक यूआरआई टेम्पलेट एक एपीबंडल के लिए उपयुक्त होगा

http://swagger.wordnik.com/ से अवधारणाएं लेने में सक्षम हो सकते हैं

: +1: स्वैगर के लिए। यह कमाल लग रहा है!

एक समान अनुभव बनाने के लिए हम निम्न में सक्षम हो सकते हैं:

• पार्स विधियों को @apidoc या कुछ के रूप में चिह्नित किया गया है
• @apidoc चिह्नित विधियों पर डॉकब्लॉक से विधि और पैरामीटर का विवरण प्राप्त करें
• प्रति क्रिया के आधार पर कॉलों के इनलाइन-परीक्षण की अनुमति दें।

कुल मिलाकर मुझे लगता है कि स्वैगर जैसी स्क्रीन हासिल करना काफी सक्षम है और इस बंडल के लिए बहुत मायने रखता है।

एक अन्य विकल्प केवल JSON उत्पन्न करना होगा जो स्वैगर उपभोग करता है लेकिन वह कुछ वजन (जावा) के साथ आता है ... बल्कि "पसंद" कार्यान्वयन को देखेगा।

संगत JSON उत्पन्न करना मेरा पहला विचार था। मैं सप्ताहांत में थोड़ा गहरा खोदूंगा, हो सकता है कि कुछ त्वरित 'एन गंदा प्रोटोटाइप संभव हो।

@pminnieur ऐसा लगता है जैसे हम आसानी से एकीकृत करने के बजाय समान बुनियादी कार्यक्षमता प्रदान कर सकते हैं।

कम से कम यह https://github.com/FriendsOfSymfony/FOSJsRoutingBundle की तरह काम कर सकता है - बस कुछ फैंसी HTML/CSS जोड़ना और किसी प्रकार के एपीआई दस्तावेज़ों के साथ अपने रीस्टफुल मार्गों का पर्दाफाश करना। हो सकता है कि हम अधिक सूचनाओं का समर्थन करने के लिए कुछ एनोटेशन का उपयोग कर सकें।

मैं इसके साथ शुरुआत करना चाहता हूं लेकिन मुझे लगता है कि कोड को एक समर्पित बंडल में रखना बेहतर होगा (उदाहरण के लिए FOSRestAPIExplorerBundle)। प्रश्न यह है कि क्या हम केवल स्वैगर एपीआई का समर्थन करेंगे (इसलिए स्वैगर का उपयोग JSON में एकत्रित और उजागर की गई जानकारी की कल्पना करने के लिए किया जाता है) या क्या हम अपना स्वयं का वेब इंटरफ़ेस भी प्रदान करेंगे?

एक अलग बंडल एक अच्छे विचार की तरह लगता है। अगर हम केवल स्वैगर का समर्थन करते हैं तो हम बंडल नाम में ऐसा कहना चाह सकते हैं। मुझे नहीं पता कि हम भी किसी और चीज का समर्थन करना चाहते हैं। आपकी प्रेरणा और स्वैगर की गुणवत्ता पर निर्भर करता है। स्वैगर के बारे में एक प्रश्न: यह आंतरिक एपीआई के साथ कैसे काम करता है कि कोई बाहरी सेवा को उजागर नहीं करना चाहता है?

मुझे लगता है कि अगर आप इसे सार्वजनिक नहीं करना चाहते हैं तो आपको स्वैगर JSON को वापस करने वाले URL को सार्वजनिक नहीं करना है ...:D गंभीरता से, मैं एनोटेशन का उपयोग करना चाहता हूं और यदि आप कोई मार्ग नहीं चाहते हैं सार्वजनिक, आप @Expose() एनोटेशन नहीं जोड़ेंगे या @Expose(false) जोड़ेंगे - ऐसा कुछ। जैसे FOSJsRoutingBundle कॉन्फ़िगर करने योग्य है कि इससे कैसे निपटें (डिफ़ॉल्ट रूप से सब कुछ उजागर करें, या श्वेतसूची का पर्दाफाश करें)। यदि आपका मतलब है "यहां हमारे सार्वजनिक एपीआई के लिए एक लिंक है और यह लिंक केवल आपके लिए है", तो हम सुरक्षा घटक सहित @Api("public") और @Api("private") जैसे एनोटेशन जोड़ सकते हैं ताकि आप अलग एपीआई सौंप सकें अलग-अलग लोगों के लिए दस्तावेज (और 'उन्हें' तक पहुंच को नियंत्रित करते हैं)।

नाम के लिए: मैं एक सामान्य नाम रखना चाहता हूं, स्वैगर समर्थित होने वाली पहली एपीआई दस्तावेज सेवा होगी। अगर लोग कोई अन्य सेवा जोड़ना चाहते हैं, तो वे इसे कर सकते हैं (और खरोंच से शुरू नहीं करना चाहिए)। उदाहरण के लिए @odino WADL समर्थन जोड़ सकता है। कम से कम मैं एक वेब इंटरफेस भी प्रदान करना चाहता हूं।

मैंने शुरू करने से पहले विचारों और मुद्दों को एकत्र करने के लिए अब तक एक गिटहब भंडार बनाया है। किसी भी प्रश्न या विषयों पर चर्चा करने के लिए स्वतंत्र महसूस करें (नामकरण पर भी चर्चा की जा सकती है, निश्चित रूप से) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

ठीक अच्छा। एक बार चीजें आकार लेने के बाद .. हम इसे FOS में स्थानांतरित कर सकते हैं

क्या आप "डिस्प्लेर" के रूप में https://github.com/wordnik/swagger-ui का लाभ उठाने की योजना बना रहे हैं?

पहली जगह में, हाँ। स्वैगर-यूआई द्वारा उपयोग किए जाने के लिए केवल स्वैगर-स्पेक अनुरूप जेसन उत्पन्न करें।

https://github.com/nelmio/NelmioApiDocBundle के पक्ष में समापन

मुझे पता है कि यह बहुत पुराना है, लेकिन तब से कुछ चीजें बदल गईं और स्वैगर/ओपनपी के लिए पैकेज/बंडल की तलाश में मुझे यह अपेक्षाकृत तेज़ी से मिला।
इस पर पुनर्विचार करने का कोई मौका? चूंकि NelmioApiDocBundle को छोड़ दिया गया है और मुझे कोई वास्तविक विकल्प नहीं दिख रहा है जो स्वैगर / OpenApi (या किसी अन्य वास्तव में, RAML, ...?) के लिए सिम्फनी में एकीकृत हो।