Api-blueprint: نمطية

بالنسبة لتلك المواقف التي يوجد فيها عدد كبير من واجهات برمجة التطبيقات ، ربما تكون تحت سيطرة مجموعات مختلفة في الشركة ، سيكون هذا بمثابة هبة من السماء.

rurounijones فقط للتوضيح ، هذه الميزة تعني "القدرة على تقسيم وصف واحد لواجهة برمجة التطبيقات إلى ملفات متعددة".

أي شخص لديه أي أفكار حول هذا؟ حسب تعليقي السابق على Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

الخيارات هي إما إضافة بعض التضمين / طلب مرفق في الجزء العلوي من المخطط أو ببساطة إحضار جميع المخططات من دليل وربطها معًا.

أفكار؟

التسلسل أبسط ولكني أشعر أنه سيكون من الأسهل استخدامه كما قد ترغب في ذلك ، ثم أضف شيئًا آخر بعد ذلك.

هل سيكون هذا مجرد تضمين محتويات الملف بشكل أعمى كما لو تم تعريفه في براءة الاختراع ، أم سيكون هناك نوع من القيود على محتويات الملف (على سبيل المثال ، هل يمكن أن يكون لديهم رأس yaml الخاص بهم؟ تتعارض مع yaml الأصل؟) لدي شعور بأنه لن يكون من الأفضل عدم وجود قيود ولكني اعتقدت أنني سأطرحها.

تضمين التغريدة

أولاً ، لدي نظام بدائي لإدارة هذا بالفعل باستخدام Grunt ، باستخدام تسلسل بسيط للملفات. أصبح مخططنا غير قابل للإدارة ، وكانت هذه طريقة سريعة وقذرة لتقسيمه إلى ملفات (ملحوظة ، العديد من الملفات العشوائية ، لأنها متسلسلة بترتيب نظام الملفات). لقد قمت بنشر Gruntfile الخاص بي مع شرح موجز هنا .

بالنظر إلى أن التسلسل سهل للغاية للتعبير عن نفسك ، فمن المنطقي بالنسبة لي أن تكون الأداة "الرسمية" أكثر قوة. لقد كنت أفكر أكثر في هذا الأمر ، محاولًا إجراء بعض الأبحاث حول كيفية التعامل مع هذا من قبل الأنظمة الأخرى.

1. تضمين / طلب
   
   
   
   • سيتم عمل التضمينات في الجزء العلوي من الملف ، وسيتم الإشارة إلى أجزاء من الملف بداخله. أعتقد أن هذا يتطلب نظامًا مرجعيًا أكثر قوة من بناء الجملة الحالي [Model Reference][] . من الناحية المثالية ، ستكون أي عقدة في الملف المضمن قابلة للعنونة - لذلك قد يكون لدى المرء شيء مثل [github.Users.'Create A User'][] أو [github][POST /users] أو شيء من هذا القبيل. (قد تحتاج أيضًا إلى بادئة مثل = ). هل هناك طريقة أفضل للإشارة إلى عقدة معينة في AST بخلاف الاسم أو طريقة url +؟
   
   
   • بالنظر إلى أن لديك طريقة جيدة لإلغاء مرجع محتويات العقدة ، يمكن القيام بذلك باستخدام معالج C المسبق الذي سيأتي مع الكثير من الميزات الإضافية دون أي تكلفة إضافية.
   
   
2. نظام القوالب / التحويل
   
   
   
   • Non-markdown - سيتم كتابة النموذج بلغة قوالب منفصلة ، لذلك لن يكون ملف القالب قابلاً للتحليل بواسطة Snowcrash. مثال على شيء مثل هذا هو grunt-readme ، والذي يبدو أنه يمكن أن يعمل خارج الصندوق لصياغة ملف مخطط.
   
   
   • تخفيض السعر - سيكون هذا شيئًا مثل بناء الجملة =[]() أو :[]() الذي ناقشناه حول مشكلة الصياغة. سيظل تخفيض السعر صالحًا وقابل للتحليل بواسطة تساقط الثلوج.
   
   
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

Ad 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

أعتقد أن هذا يمكن أن يكون كافيا للبداية؟

أعتقد أن هذا يمكن أن يكون كافيا للبداية؟

متفق. أنا أدرك الآن أنك تقوم بالتمييز بين تضمين "الأصول" وتضمين "الموارد" / "مجموعات الموارد". كنت أفكر في كل منهم على أنه "عقد" يتم تضمينها حسب الرغبة.

بالنسبة للنقطة الثانية ، اعتقدت أنه سيكون من المفيد الإشارة إلى بناء جملة MultiMarkdown الحالي من أجل التضمين:

This is some text.

{{some_other_file.txt}}

Another paragraph

هذا يبدو وكأنه طريقة بسيطة لتضمين الموارد؟ (أو في الواقع ، نص / عقد عشوائية؟)

لتوضيح رأيي:

1. أعتقد أن البنية الجيدة للأصول المشار إليها ستكون :[]() أو =[]() كما تمت مناقشته
2. أعتقد أن بناء الجملة الجيد للترجمة سيكون {{ }} كما هو مستخدم بواسطة multimarkdown.

وأيضًا لتوضيح بعض المفردات: أعتقد أنه عندما تقول "تضمين" فأنت تشير إلى ما أعنيه عندما أقول "تضمين" ، أي استبدال عنصر نائب بالكامل بنص من ملف آخر.

إذا كنت أفهم بشكل صحيح ، فإن الفرق بين "الإشارة" و "التضمين" / "الاستبدال" هو ببساطة من أجل _rendering_ ، على سبيل المثال في html أو pdf. بالنسبة إلى المحلل اللغوي ، لا يهم إذا تمت الإشارة إلى أحد الأصول (على سبيل المثال) أو استعادته ، نفس نتائج AST. هل هذا صحيح؟

1. أعتقد أن التركيب الجيد للأصول المشار إليها سيكون: أو = كما تمت مناقشته
2. أعتقد أن البنية الجيدة للشفافية ستكون {{}} كما هي مستخدمة في عمليات الشطب المتعددة.

لماذا يكون لديك كلاهما بدلاً من طريقة واحدة فقط؟ هل هناك أي فائدة للتمييز النحوي بين هذين؟ أنا شخصياً أفضل رقم واحد لأنه لا يزال يظهر على أنه يمكنك اتباعه في Markdown عادي؟

أعتقد أنه عندما تقول "تضمين" فأنت تشير إلى ما أعنيه عندما أقول "تضمين" ، أي استبدال عنصر نائب بالكامل بنص من ملف آخر.

موافق ، سأحاول استخدام التضمين من الآن فصاعدًا. شكرا!

إذا فهمت بشكل صحيح ، فإن الفرق بين "الإشارة" و "التضمين" / "الاستبعاد" هو ببساطة من أجل العرض

ليس صحيحا. في رأيي ، فإن الإشارة (إنشاء مرجع) يجب أن تضيف فقط رابطًا إلى الإخراج (AST) وتترك الباقي على الأدوات (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

يجب أن يوجه Translcusion المحلل اللغوي (أو المعالج المسبق) لسحب المحتوى ...

مجرد تحديث هنا: هذا مخطط بالفعل وهناك حاجة ماسة إليه. نحن نعمل على الأداة التي تجعل هذا ممكنًا. وفي الوقت نفسه ، إذا كنت لا تعتمد على محرر Apiary عبر الإنترنت ، فيمكنك القيام بشيء مثل https://gist.github.com/danvine/11087404 أو نهج آخر مشابه (أعرف على الأقل القليل من الأدوات المستندة إلى gulp لهذا الغرض).

يدعم Whiskey الآن الامتداد .apib ويجعل تحرير ملفات Markdown الكبيرة أسهل بكثير من خلال عرض المخطط التفصيلي: http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ و http://25.io/mou/ يدعمان أيضًا .apib إذا كنت تريد تطبيق سطح مكتب (لنظام Mac)

روبرت كروكس مدير خدمات التعلم
برايتكوف ، إنك

في 29 ديسمبر 2015 ، الساعة 4:08 مساءً ، كتب Kevin Ingersoll [email protected] :

يدعم ويسكي الآن ملف
التمديد ويجعل تحرير ملفات Markdown الكبيرة أسهل بكثير من خلال عرض المخطط التفصيلي الخاص به: http://vimeo.com/album/3108294/video/110486733

-
قم بالرد على هذا البريد الإلكتروني مباشرة أو قم بعرضه على GitHub
.

مرحبًا bcls و @ holic ، شكرًا على الإشارة إلى هؤلاء المحررين!

ذات صلة: https://github.com/apiaryio/api-blueprint/issues/20#issuecomment -77108398

هل تم اتخاذ أي قرار من قبل المطورين الأساسيين في هذا الشأن؟ لقد كان الأمر رائعًا منذ عام 2013 ولم يتم تقديم إجابة واضحة حتى الآن ، هل يمكننا رسم خط حول هذا من فضلك؟

مرحبًا foxx ، لم يكن هناك أي قرار واضح بشأن هذا الأمر حتى الآن - أنا أميل نحو بناء جملة التضمين المقدم في Hercule :

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 مني.

اي اخبار عن هذا؟

يبدو أن النهج مع التحويل يبدو جيدًا بالنسبة لي ، ولا أرى أي عيوب لذلك.

في الوقت الحالي ، أقترح استخدام Hercule وبناء الجملة :[Gist](blueprint/gist.md) . ستعمل على إعادة نقلها إلى مواصفات مخطط API وسلسلة أدوات المحلل اللغوي

هل تم فعل أي شيء لهذه القضية؟ أود أيضًا تقسيم ملف apib أكبر إلى عدة ملفات.
شكرا!

يا @ adams-sarah للأسف ليس من جانبي. ما زلت أؤيد استخدام Hercule (https://github.com/jamesramsay/hercule) لأنه يعمل بشكل جيد - العيب الوحيد هو أنك لن تكون قادرًا على تحرير الملفات المتعددة في Apiary.io. اسمحوا لي أن أعرف إذا كان بإمكاني المساعدة بطريقة ما!

+1 لاستخدام هرقل https://github.com/jamesramsay/hercule
لقد استخدمناها منذ فترة ونأمل أن تجد طريقها إلى مواصفات apib

: +1: لإضافة هذه الميزة.

أنا أؤيد أيضًا منهجية واحدة لجدول المحتويات / مؤشر. يعتبر Transclusion مرنًا جدًا إلى حد ما ولم يتم تغيير حجمه في المستندات الكبيرة المستندة إلى wiki في تجربتي السابقة.

سيتعين علينا بالتأكيد خبز هذا في المحلل اللغوي نفسه لدعم خريطة المصدر.

في غضون ذلك ، قمنا بإعداد مثال حقيقي لإظهار كيفية استخدام Hercule - https://github.com/apiaryio/api.apiblueprint.org

zdne في استخدامنا لـ json-schema (عبر interagent / prmd) قمنا بتقسيمه على طول خطوط الموارد وفرض بشكل أساسي بنية دليل معينة لتضمين التضمينات (بشكل أو بآخر يقوم ببناء مخطط مستوى أعلى يحتوي على جميع العناصر الموجودة في الدليل مثل المخططات الفرعية ، لذلك فهي تغير مستويات الأشياء). من الواضح أن هذا متخصص جدًا فيما كنا نفعله وليس مناسبًا بشكل خاص في حالتك ، لكننا أردنا مشاركة تجربتنا. مقارنةً بذلك ، أعتقد أن التحويل يبدو أكثر أناقة / مرونة ، ولكن سيكون من الجيد بالتأكيد أن يكون لديك بعض الوسائل المباشرة للحصول على جدول المحتويات / فهرس موحد. ربما يكون هذا مشابهًا لما فعلناه ، على سبيل المثال ، تقوم بإنشاء مخطط uber ليكون بمثابة هذا الفهرس ثم تستبعد / تشير إلى المخططات الفرعية داخله. أستطيع أن أرى أن ذلك يحدث تلقائيًا على أنه أمر لطيف ، ولكن أيضًا على أنه أمر محرج إذا لم يحدث ما تريده تمامًا. على أي حال ، طريق طويل للقول إنني سأكون سعيدًا بمناقشة / مشاركة تجاربي بشكل أكبر إذا كان ذلك مفيدًا.

ما هي حالة هذه الميزة؟
نحن نستخدم خطة Pro في Apiary.io ونحتاج إلى هذه الميزة

DavidBM لدي نفس المشكلة. كيف يمكنني التغلب على هذا هو الحصول على وثيقتين 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

لقد حصلنا بالفعل على الحل المخصص مع Hercule ، ولكن الهدف من دفع apiary pro بالنسبة لنا هو السماح لمديري المنتج بتحديث الوثائق دون الدخول في git. أخشى أن يكون هذا مانعًا تمامًا لنا وسنلغي العقد مع Apiary إذا لم يتم حل هذا الأمر.

لا أتوقع أن يكون هذا في هذه الحالة بعد توفر Hercule وأدوات أخرى لوقت طويل.

هذا مخيب جدا للآمال :(

مرحبًا بالجميع ، أنا آسف لوصولي متأخرًا وإعادة فتح الأشياء القديمة وحفرها. إذا لم يكن هذا هو المكان المناسب ، أرجوك سامحني. ولكن ، أثناء إجراء بحث لتطوير نماذج المخططات ، وجدت هذه المناقشة وهذا هو أقرب ما يمكن أن أجده حتى الآن.

أجد صعوبة في تقسيم ردودي حسب النموذج :(. أليس من الممكن إحالة نموذج إلى مجلد مختلف؟
أرغب في الحصول على جميع طلباتي داخل مجلد المخططات الخاصة بي ، وعلى سبيل المثال في مجلد نماذج منفصل ، جميع نماذج الكيانات الخاصة بي (MSON / MD / JSON / أي ملفات تناسبها) لإعادة استخدامها في استجابات مختلفة بسهولة. أي شخص لديه النجاح في فعل هذا؟

سيكون رائعًا حقًا إذا حظيت هذه المشكلة ببعض الاهتمام. لدينا 26000 سطر في مخطط API الخاص بنا وهذا يجعل من الصعب للغاية إدارتها

نحن ننفذ اختبار العقد باستخدام Dredd ونستخدم Aglio ، ولكن سيكون من الرائع إذا تمت إضافة هذا حتى لا نضطر إلى ذلك

أحد الأسباب هو أننا نكرر التصميم كثيرًا :) عندما تم فتح هذه المشكلة ، لم يكن هناك MSON وما زلنا ممزقين بشأن الترجمات مقابل المراجع.

لكن للتسجيل ، ما هي احتياجاتك هناك؟ هل هي مجرد إدارة متعددة الملفات وتجميع مستند واحد كنتيجة لذلك أم أنك تتحدث أيضًا عن إمكانية إعادة استخدام النماذج ومشاركة البتات والقطع عبر مستندات وصف متعددة لواجهة برمجة التطبيقات؟

أحد الأسباب هو أننا نكرر التصميم كثيرًا :) عندما تم فتح هذه المشكلة ، لم يكن هناك MSON وما زلنا ممزقين بشأن الترجمات مقابل المراجع.

لكن للتسجيل ، ما هي احتياجاتك هناك؟ هل هي مجرد إدارة متعددة الملفات وتجميع مستند واحد كنتيجة لذلك أم أنك تتحدث أيضًا عن إمكانية إعادة استخدام النماذج ومشاركة البتات والقطع عبر مستندات وصف متعددة لواجهة برمجة التطبيقات؟

لدينا استجابة قياسية تأتي من مجموعة من نقاط النهاية لدينا. نود أن نكون قادرين على تحديد ذلك في مكان واحد ، بالقرب من المكتبة التي تضمها ، ثم نقوم باستيرادها حيثما احتجنا إلى الرد عليها.