Api-blueprint: प्रतिरूपकता

उन स्थितियों के लिए जहां बड़ी संख्या में एपीआई हैं, संभवतः एक कंपनी में विभिन्न समूहों के नियंत्रण में, यह एक पूर्ण देवता होगा।

@rurounijones सिर्फ स्पष्टीकरण के लिए इस सुविधा का अर्थ है "एक एपीआई विवरण को कई फाइलों में विभाजित करने में सक्षम होना"।

किसी के पास इस पर कोई विचार है? मेरी पिछली टिप्पणी के अनुसार Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

विकल्प या तो ब्लूप्रिंट के शीर्ष पर कुछ शामिल / आवश्यकता सुविधा जोड़ते हैं या बस सभी ब्लूप्रिंट को एक निर्देशिका बनाते हैं और उन्हें एक साथ जोड़ते हैं।

विचार?

संयोजन सरल है, लेकिन मुझे लगता है कि आवश्यकता का उपयोग करना आसान होगा क्योंकि आप इसकी आवश्यकता हो सकती है, फिर बाद में कुछ और जोड़ें।

क्या यह फ़ाइल की सामग्री को अंधाधुंध रूप से रेखांकित करेगा जैसे कि इसे पेटेंट में परिभाषित किया गया था, या फ़ाइल की सामग्री पर किसी प्रकार का प्रतिबंध होगा (उदाहरण के लिए क्या उनके पास अपना स्वयं का yaml शीर्षलेख हो सकता है? माता-पिता yaml के साथ संघर्ष?) मुझे लग रहा है कि कोई प्रतिबंध बेहतर नहीं होगा, लेकिन सोचा कि मैं इसे लाऊंगा।

@zdne

सबसे पहले, मेरे पास सरल फ़ाइल संयोजन का उपयोग करके, पहले से ही ग्रंट के साथ इसे प्रबंधित करने के लिए एक प्राथमिक प्रणाली है। हमारा ब्लूप्रिंट अप्रबंधनीय होता जा रहा था, और इसे फाइलों में विभाजित करने का यह एक त्वरित और गंदा तरीका था (ध्यान दें, मनमाने ढंग से कई फाइलें, क्योंकि वे फाइल सिस्टम ऑर्डर द्वारा संयोजित हैं)। मैंने अपना ग्रंटफाइल यहां एक संक्षिप्त स्पष्टीकरण के साथ पोस्ट किया है।

यह देखते हुए कि संयोजन स्वयं को रोल करने के लिए इतना आसान है, यह मेरे लिए समझ में आता है कि एक "आधिकारिक" उपकरण अधिक शक्तिशाली होना चाहिए। मैं इसके बारे में और सोच रहा हूं, कुछ शोध करने की कोशिश कर रहा हूं कि यह अन्य प्रणालियों द्वारा कैसे नियंत्रित किया जाता है।

1. शामिल करें/आवश्यकता
   
   
   
   • फ़ाइल के शीर्ष पर शामिल किया जाएगा, और फ़ाइल के कुछ हिस्सों को संदर्भित किया जाएगा। मुझे लगता है कि इसके लिए मौजूदा [Model Reference][] सिंटैक्स की तुलना में अधिक मजबूत संदर्भ प्रणाली की आवश्यकता है। आदर्श रूप से शामिल फ़ाइल में कोई भी नोड पता करने योग्य होगा - इसलिए किसी के पास [github.Users.'Create A User'][] या [github][POST /users] या कुछ ऐसा हो सकता है। ( = जैसे उपसर्ग की भी आवश्यकता हो सकती है)। क्या नाम या यूआरएल + विधि के अलावा एएसटी में किसी विशिष्ट नोड को संदर्भित करने का कोई बेहतर तरीका है?
   
   
   • यह देखते हुए कि आपके पास नोड सामग्री को हटाने का एक अच्छा तरीका है, यह सी प्रीप्रोसेसर के साथ किया जा सकता है जो बिना किसी अतिरिक्त लागत के कई अतिरिक्त सुविधाओं के साथ आएगा।
   
   
2. टेम्प्लेटिंग सिस्टम / ट्रांसक्लूज़न
   
   
   
   • गैर-मार्कडाउन - टेम्प्लेट एक अलग टेम्प्लेटिंग भाषा में लिखा जाएगा, इसलिए एक टेम्प्लेट फ़ाइल स्नोक्रैश द्वारा पार्स करने योग्य नहीं होगी। कुछ इस तरह का एक उदाहरण ग्रंट-रीडमे है, जो ऐसा लगता है कि यह ब्लूप्रिंट फ़ाइल को टेम्प्लेट करने के लिए बॉक्स से बाहर काम कर सकता है।
   
   
   • मार्कडाउन - यह =[]() या :[]() सिंटैक्स जैसा कुछ होगा जिसकी हमने ड्राफ्टर मुद्दे पर चर्चा की थी। यह अभी भी मान्य मार्कडाउन और स्नोक्रैश द्वारा पार्स करने योग्य होगा।
   
   
3. दोनों
   
   
   
   • यह देखते हुए कि आप नोड्स ( [github]['Create A User'] ) और प्रत्यक्ष ट्रांसक्लूजन ( :[/github.md](/github.md) ) को संदर्भित करने के लिए एक वाक्यविन्यास परिभाषित करते हैं, ऐसा लगता है कि आप दोनों को आसानी से प्राप्त कर सकते हैं। शायद उनके पास समान सामान्य वाक्यविन्यास हो सकता है जैसे :[]() और पार्सर निर्धारित करता है कि यह नोड या फ़ाइल संदर्भ है या नहीं।
   
   

इस पर कोई विचार? क्या मुझे कुछ विकल्प/उपकरण याद आ रहे हैं? मैं ट्रांसक्लूजन और नोड डीरेफ्रेंसिंग के लिए एक सामान्य सिंटैक्स के साथ "दोनों" विकल्प की ओर झुकाव कर रहा हूं, लेकिन शायद यह थोड़ा अधिक है।

यह देखते हुए कि संयोजन स्वयं को रोल करने के लिए इतना आसान है, यह मेरे लिए समझ में आता है कि एक "आधिकारिक" उपकरण अधिक शक्तिशाली होना चाहिए

खैर अंत में शायद हाँ, लेकिन मैं इसे अधिक डिज़ाइन नहीं करना चाहता और भीख मांगने में कुछ दुबला और सरल रोल आउट करना चाहता हूं।

वर्तमान समस्याओं को देखते हुए जिन्हें संबोधित करने की आवश्यकता है, यह मुख्य रूप से है:

1. संदर्भित (बाहरी) संपत्तियां - #20 और जैसा कि https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071 में चर्चा की गई है
2. ब्लूप्रिंट को अधिक प्रबंधनीय तार्किक भागों में विभाजित करना

बंटवारे के उद्देश्य के लिए मैं केवल या तो एक संसाधन समूह या एक संसाधन पर विचार करूंगा (उदाहरण के लिए कोई कार्रवाई नहीं, लेन-देन का उदाहरण, या एक अनुरोध)। कम से कम शुरुआत में।

विज्ञापन 1: मुझे लगता है कि _संदर्भित संपत्ति_ को #20 में प्रस्ताव द्वारा सुंदर ढंग से संबोधित किया जाएगा और https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071 पर चर्चा की जाएगी।

विज्ञापन 2: मैं इसे बिल्कुल भी जटिल नहीं करूँगा। केवल एक चीज जो मैं ट्रांसक्लूजन के लिए उपयोग करूंगा वह है नियमित मार्कडाउन सिंटैक्स जैसे [Some Text](path/to/blueprint/file.apib) या [Some Text](path/to/blueprint/file.apib#resource-name) । शामिल करने के लिए मैं उसी सिद्धांत का पालन करूंगा जैसे कि ड्राफ्टर में संपत्ति के लिए उदाहरण के लिए संदर्भ से पहले : का उपयोग करें। https://gist.github.com/zdne/8804418#aliens -question-aliens_question जैसा कुछ

मुझे लगता है कि यह शुरुआत के लिए पर्याप्त हो सकता है?

मुझे लगता है कि यह शुरुआत के लिए पर्याप्त हो सकता है?

माना। मैं अभी महसूस कर रहा हूं कि आप "संपत्ति" और "संसाधन"/"संसाधन समूह" सहित अंतर कर रहे हैं। मैं उन सभी के बारे में सोच रहा था कि वे "नोड्स" के रूप में शामिल होंगे।

दूसरे बिंदु के लिए, मुझे लगा कि ट्रांसक्लूजन के लिए मौजूदा मल्टीमार्कडाउन सिंटैक्स को संदर्भित करना उपयोगी होगा:

This is some text.

{{some_other_file.txt}}

Another paragraph

यह संसाधनों को शामिल करने का एक आसान तरीका लगता है? (या वास्तव में, मनमाना पाठ/नोड्स?)

तो मेरी राय स्पष्ट करने के लिए:

1. मुझे लगता है कि संदर्भित संपत्तियों के लिए एक अच्छा वाक्यविन्यास :[]() या =[]() जैसा कि चर्चा की गई है
2. मुझे लगता है कि ट्रांसक्लूजन के लिए एक अच्छा सिंटैक्स {{ }} होगा जैसा कि मल्टीमार्कडाउन द्वारा उपयोग किया जाता है।

और कुछ शब्दावली को स्पष्ट करने के लिए भी: मैं _थिंक_ कि जब आप "समावेशन" कहते हैं, तो आप मेरे मतलब का उल्लेख कर रहे हैं जब मैं "ट्रांसक्लूजन" कहता हूं, अर्थात, प्लेसहोल्डर को पूरी तरह से किसी अन्य फ़ाइल से टेक्स्ट के साथ बदलना।

अगर मैं सही ढंग से समझ रहा हूं, तो "संदर्भ" और "समावेशन"/"स्थानांतरण" के बीच का अंतर केवल _rendering_ के लिए है, जैसे html या pdf में। पार्सर के लिए, इससे कोई फर्क नहीं पड़ता कि कोई संपत्ति (उदाहरण के लिए) संदर्भित या स्थानांतरित की गई है, वही एएसटी परिणाम। क्या वो सही है?

1. मुझे लगता है कि संदर्भित संपत्तियों के लिए एक अच्छा वाक्यविन्यास होगा: या = जैसा कि चर्चा की गई है
2. मुझे लगता है कि ट्रांसक्लूजन के लिए एक अच्छा सिंटैक्स {{}} होगा जैसा कि मल्टी मार्कडाउन द्वारा उपयोग किया जाता है।

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

मुझे लगता है कि जब आप "समावेशन" कहते हैं, तो आप मेरे कहने का मतलब "ट्रांसक्लूजन" कह रहे हैं, यानी, प्लेसहोल्डर को पूरी तरह से किसी अन्य फ़ाइल से टेक्स्ट के साथ बदलना।

सहमत हूं, अभी से ट्रांसक्लूजन का उपयोग करने का प्रयास करूंगा। धन्यवाद!

अगर मैं सही ढंग से समझ रहा हूं, तो "संदर्भ" और "समावेशन"/"स्थानांतरण" के बीच का अंतर केवल प्रतिपादन के लिए है

ज़रुरी नहीं। मेरी राय में (एक संदर्भ बनाना) वास्तव में केवल आउटपुट (एएसटी) के लिए एक लिंक जोड़ना चाहिए और बाकी को टूलिंग पर छोड़ देना चाहिए (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

ट्रांसल्यूशन को सामग्री को खींचने के लिए पार्सर (या प्रीप्रोसेसर) को निर्देश देना चाहिए ...

बस यहां एक अपडेट: यह वास्तव में योजनाबद्ध है और इसकी बहुत आवश्यकता है। हम उस टूल पर काम कर रहे हैं जो इसे संभव बनाता है। इस बीच, यदि आप एपीरी ऑनलाइन संपादक पर भरोसा नहीं करते हैं, तो आप https://gist.github.com/danvine/11087404 या किसी अन्य समान दृष्टिकोण की तरह कुछ कर सकते हैं (मैं इसके लिए कुछ गल्प-आधारित टूल के बारे में जानता हूं)।

व्हिस्की अब .apib एक्सटेंशन का समर्थन करता है और बड़ी मार्कडाउन फ़ाइलों को इसके रूपरेखा दृश्य के साथ संपादित करना बहुत आसान बनाता है: http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ और http://25.io/mou/ भी .apib का समर्थन करते हैं यदि आप एक डेस्कटॉप ऐप चाहते हैं (मैक के लिए)

रॉबर्ट क्रुक्स लर्निंग सर्विसेज के निदेशक
ब्राइटकोव, इंक

29 दिसंबर 2015 को शाम 4:08 बजे केविन इंगरसोल नोटिफिकेशन @github.com ने लिखा:

व्हिस्की अब .apib . का समर्थन करती है
विस्तार और बड़ी मार्कडाउन फ़ाइलों को अपने रूपरेखा दृश्य के साथ संपादित करना बहुत आसान बनाता है: http://vimeo.com/album/3108294/video/110486733

-
इस ईमेल का सीधे उत्तर दें या इसे GitHub पर देखें
.

अरे @bcls और @holic , इन संपादकों को इंगित करने के लिए धन्यवाद!

संबंधित: https://github.com/apiaryio/api-blueprint/issues/20#issuecomment -77108398

क्या कोर डेवलपर्स द्वारा इस पर कोई निर्णय लिया गया है? यह 2013 से बकाया है और अब तक कोई स्पष्ट उत्तर नहीं दिया गया है, क्या हम इस पर एक रेखा खींच सकते हैं?

अरे @foxx इस पर अभी तक कोई स्पष्ट निर्णय नहीं हुआ था - मैं हरक्यूल में पेश किए गए ट्रांसक्लूजन सिंटैक्स की ओर झुक रहा हूं:

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

# Group Gist

:[Gist](blueprint/gist.md)

:[Gists](blueprint/gists.md)

के अपवाद के साथ

`````` मार्कडाउन

• नमूना

+ Body

  ```
  :[](gist.json)
  ```

``````

क्योंकि कोड ब्लॉक पार्सर/प्रीप्रोसेसर के लिए अपारदर्शी रहना चाहिए।

इसके अलावा, मुझे नहीं लगता कि ट्रांसक्लूजन किसी भी स्तर पर काम करना चाहिए - ट्रांसक्लूड की जा रही फाइलें वैध ब्लूप्रिंट ही होनी चाहिए।

इसके प्रति प्रतिबद्धता के लिए - यह सुविधाओं के रोडमैप पर काफी अधिक है - लेकिन अभी तक कोई ईटीए नहीं है।

मैं इस पर और रोडमैप दृश्यता सुविधाओं पर किसी भी टिप्पणी या विचार की सराहना करता हूं।

धन्यवाद!

ट्रांसक्लूजन सिंटैक्स अब तक का सबसे अच्छा प्रस्ताव जैसा लगता है, यह एक सुंदर और साफ दृष्टिकोण है, और अब तक मैंने जो भी अन्य सुझाव देखे हैं, उससे बेहतर है। Fwiw, मुझसे +1।

इस पर कोई भी समाचार?

ट्रांसक्लूजन के साथ दृष्टिकोण मुझे अच्छा लगता है, मुझे इसके लिए कोई नुकसान नहीं दिखता है।

फिलहाल मैं हरक्यूल और :[Gist](blueprint/gist.md) सिंटैक्स का उपयोग करने का सुझाव देता हूं। इसे वापस एपीआई ब्लूप्रिंट स्पेक और पार्सर टूलचेन में बैकपोर्ट करने की दिशा में काम करेगा

क्या इस मुद्दे के लिए कुछ किया गया है? मैं एक बड़ी एपीबी फ़ाइल को एकाधिक में विभाजित करना चाहता हूं।
धन्यवाद!

अरे @ एडम्स-सारा दुर्भाग्य से मेरी तरफ से नहीं। मैं अभी भी हरक्यूल (https://github.com/jamesramsay/hercule) के उपयोग का समर्थन करता हूं क्योंकि यह बहुत अच्छी तरह से काम करता है - एकमात्र दोष यह है कि आप Apiary.io पर कई फाइलों को संपादित नहीं कर पाएंगे। मुझे बताएं कि क्या मैं किसी तरह मदद कर सकता हूं!

+1 हरक्यूल के उपयोग के लिए https://github.com/jamesramsay/hercule
हम इसे कुछ समय से उपयोग कर रहे हैं और आशा करते हैं कि यह अभी भी एपीब स्पेक्स में अपना रास्ता खोज लेगा

:+1: इस सुविधा को जोड़ने के लिए।

मैं एकल टीओसी/सूचकांक पद्धति का भी समर्थन करता हूं। ट्रांसक्लूजन थोड़ा बहुत लचीला है और मेरे पिछले अनुभव में बड़े विकी-आधारित दस्तावेज़ों में स्केल नहीं किया गया है।

स्रोत मानचित्र का समर्थन करने के लिए हमें निश्चित रूप से इसे पार्सर में ही सेंकना होगा।

इस बीच, हमने हरक्यूल का उपयोग करने का तरीका दिखाने के लिए एक वास्तविक उदाहरण तैयार किया है - https://github.com/apiaryio/api.apiblueprint.org

@zdne जेसन -स्कीमा (इंटरएजेंट/पीआरएमडी के माध्यम से) के हमारे उपयोग में हम इसे संसाधन लाइनों के साथ विभाजित करते हैं और मूल रूप से समावेशन को लागू करने के लिए एक विशेष निर्देशिका संरचना को लागू करते हैं (अधिक या कम यह एक शीर्ष स्तर स्कीमा बनाता है जिसमें निर्देशिका में सभी सामान होते हैं subschemas, इसलिए यह चीजों के स्तर को बदलता है)। यह स्पष्ट रूप से हम जो कर रहे थे उसके लिए बहुत विशिष्ट है और आपके मामले में विशेष रूप से उपयुक्त नहीं है, लेकिन हम अपना अनुभव साझा करना चाहते हैं। इसकी तुलना में, मुझे लगता है कि ट्रांसक्लूजन अधिक सुरुचिपूर्ण/लचीला लगता है, लेकिन यह निश्चित रूप से अच्छा होगा कि समेकित टीओसी/इंडेक्स रखने के कुछ सरल साधन भी हों। हो सकता है कि यह वैसा ही हो जैसा हमने किया था, यानी आप इस इंडेक्स के रूप में काम करने के लिए एक uber ब्लूप्रिंट बनाते हैं और फिर इसके भीतर सब-ब्लूप्रिंट को ट्रांसक्लूड/संदर्भित करते हैं। मैं देख सकता हूं कि यह स्वचालित रूप से अच्छा होने के रूप में हो रहा है, लेकिन अजीब होने के रूप में भी अगर ऐसा नहीं होता है तो आप जो चाहते हैं उसे करने के लिए नहीं होता है। वैसे भी, कहने का लंबा रास्ता मुझे अपने अनुभवों पर चर्चा/साझा करने में खुशी होगी यदि यह सहायक होगा।

इस सुविधा की स्थिति क्या है?
हम Apiary.io में प्रो योजना का उपयोग कर रहे हैं और हमें इस सुविधा की आवश्यकता है

@ डेविडबीएम मुझे भी यही समस्या थी। मैं इसके आसपास कैसे पहुंचा, दो apiary.apib दस्तावेज़ हैं।

असंकलित

apiary-source.apib - एक असम्पीडित स्रोत जो शामिल सुविधा का उपयोग करता है

FORMAT: 1A
HOST: https://api.example.com

# Hello World

<!-- include(blueprint/posts.apib) -->

संकलन

आप बस चला सकते हैं:

aglio --input apiary-source.apib --compile --output apiary.apib

आपके apiary.apib में अब blueprint/posts.apib की सामग्री शामिल होनी चाहिए।

धन्यवाद! हाँ, लेकिन तब आप apiary.io में दस्तावेज़ों को संपादित नहीं कर सकते

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

इतने समय तक हरक्यूल और अन्य उपकरण उपलब्ध होने के बाद मैं इस स्थिति में होने की उम्मीद नहीं करता।

यह बहुत ही निराशाजनक है :(

सभी को नमस्कार, मुझे यहां देर से पहुंचने और पुराने सामान को फिर से खोलने और खोदने के लिए खेद है। अगर यह सही जगह नहीं है तो कृपया मुझे क्षमा करें। लेकिन, ब्लूप्रिंट मॉक विकसित करने के लिए एक शोध करते हुए मुझे यह चर्चा मिली है और यह अब तक के सबसे करीब है।

मैं मॉडल द्वारा अपनी प्रतिक्रियाओं को विभाजित करने के लिए संघर्ष कर रहा हूं :(। क्या किसी मॉडल को किसी भिन्न फ़ोल्डर में संदर्भित करना संभव नहीं है?
मैं अपने सभी अनुरोधों को अपने ब्लूप्रिंट फ़ोल्डर के अंदर रखना चाहता हूं, और, उदाहरण के लिए, एक अलग मॉडल फ़ोल्डर में मेरे सभी इकाइयां मॉडल (एमएसओएन/एमडी/जेएसओएन/जो भी फाइलें, जो कि फिट हैं) उन्हें आसानी से विभिन्न प्रतिक्रियाओं में पुन: उपयोग करने के लिए। क्या किसी को ऐसा करने में सफलता मिली है?

यह बहुत अच्छा होगा अगर इस मुद्दे पर कुछ ध्यान दिया जाए। हमारे एपीआई ब्लूप्रिंट में 26000 लाइनें हैं और इसे प्रबंधित करना अविश्वसनीय रूप से कठिन बना देता है

हम ड्रेड का उपयोग करके अनुबंध परीक्षण लागू कर रहे हैं और हम एग्लियो का उपयोग कर रहे हैं, लेकिन यह बहुत अच्छा होगा यदि इसे जोड़ा गया तो हमें यह नहीं करना पड़ेगा

कारणों में से एक यह है कि हम डिज़ाइन पर बहुत अधिक पुनरावृत्ति कर रहे हैं :) जब यह मुद्दा खोला गया था, कोई एमएसओएन नहीं था और हम अभी भी ट्रांसक्लूज़न बनाम संदर्भों पर फटे हुए हैं।

लेकिन रिकॉर्ड के लिए, वहां आपकी क्या जरूरतें हैं? क्या यह सिर्फ मल्टीफाइल प्रबंधन है और परिणामस्वरूप एक दस्तावेज़ को संकलित करता है या क्या आप मॉडल की पुन: प्रयोज्यता और कई एपीआई विवरण दस्तावेज़ों में बिट्स और टुकड़ों को साझा करने की बात करते हैं?

कारणों में से एक यह है कि हम डिज़ाइन पर बहुत अधिक पुनरावृत्ति कर रहे हैं :) जब यह मुद्दा खोला गया था, कोई एमएसओएन नहीं था और हम अभी भी ट्रांसक्लूज़न बनाम संदर्भों पर फटे हुए हैं।

लेकिन रिकॉर्ड के लिए, वहां आपकी क्या जरूरतें हैं? क्या यह सिर्फ मल्टीफाइल प्रबंधन है और परिणामस्वरूप एक दस्तावेज़ को संकलित करता है या क्या आप मॉडल की पुन: प्रयोज्यता और कई एपीआई विवरण दस्तावेज़ों में बिट्स और टुकड़ों को साझा करने की बात करते हैं?

हमारे पास एक मानक प्रतिक्रिया है जो हमारे समापन बिंदुओं के एक समूह से आती है। हम इसे एक ही स्थान पर, पुस्तकालय के पास परिभाषित करने में सक्षम होना चाहते हैं, और फिर इसे वहां आयात करना चाहते हैं जहां हमें इसके साथ प्रतिक्रिया करने की आवश्यकता होती है।