Api-blueprint: الأصول الخارجية

تم إنشاؤها على ١٤ أغسطس ٢٠١٣  ·  43تعليقات  ·  مصدر: apiaryio/api-blueprint

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

Language Idea Feature
مصدر
picture zdne
👍12

التعليق الأكثر فائدة

أنا مهتم بهذه القدرة ، ومن الأفضل أن تتم إضافتها عاجلاً وليس آجلاً.

حالة الاستخدام الخاصة بنا هي لتوثيق واجهات برمجة التطبيقات حيث تكون هيئات الطلب والاستجابة عبارة عن هياكل ثنائية تنتجها Apache Avro . بالنسبة لهذه الطلبات / الردود ، نود أن نكون قادرين على أن يكون "المخطط" رابطًا إما لملف تعريف مخطط Avro ، أو مستند HTML تم إنشاؤه يصف مخطط Avro المذكور. قد يبدو مثل هذا:

## POST /myresource
Creates a new myresource.

+ Request (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
+ Response 201 (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
picture davidmc24 في ٢١ أكتوبر ٢٠١٣
👍5

ال 43 كومينتر

أنا مهتم بهذه القدرة ، ومن الأفضل أن تتم إضافتها عاجلاً وليس آجلاً.

حالة الاستخدام الخاصة بنا هي لتوثيق واجهات برمجة التطبيقات حيث تكون هيئات الطلب والاستجابة عبارة عن هياكل ثنائية تنتجها Apache Avro . بالنسبة لهذه الطلبات / الردود ، نود أن نكون قادرين على أن يكون "المخطط" رابطًا إما لملف تعريف مخطط Avro ، أو مستند HTML تم إنشاؤه يصف مخطط Avro المذكور. قد يبدو مثل هذا:

## POST /myresource
Creates a new myresource.

+ Request (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
+ Response 201 (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
davidmc24 picture davidmc24 في ٢١ أكتوبر ٢٠١٣
👍5

: +1:

mhurne picture mhurne في ٢١ أكتوبر ٢٠١٣

mhurne @ davidmc24 هل فكرت تمثيل هذه الميزة في AST؟ هل ترغب في رؤية الارتباط التشعبي في AST أو يجب أن يكون المحلل اللغوي للمخطط قادرًا على جلب عنوان url الهدف وتضمين محتواه في AST؟

netmilk picture netmilk في ٢١ أكتوبر ٢٠١٣

أتوقع أن يحتوي AST على الارتباط التشعبي ، وليس محتوى الارتباط التشعبي المذكور. قد يكون من المفيد لـ AST "معرفة" أنه ارتباط تشعبي بدلاً من المحتوى المباشر ، بحيث يمكن إنتاج الروابط في وثائق HTML ، على سبيل المثال.

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

davidmc24 picture davidmc24 في ٢١ أكتوبر ٢٠١٣

MustafaHosny اللهم امين

انا فعلا أحبه. إذا كان مجرد ارتباط تشعبي ، فمن المحتمل أن يكون من السهل تنفيذه في المحلل اللغوي.

لكن التحدي الأكبر يأتي مع التغيير المطلوب في AST وأنواع وسائطها

ربما لشيء مثل هذا:

{
  "name": "<name>",
  "description": "<description>",
  "headers": {
    "<header>": {
      "value": "<header value>"
    }
  },
  "body": {
    "content": "<body>",
    "href": "<uri>"
  },
  "schema": {
    "content": "<schema>",
    "href": "<uri>"
  }
}
zdne picture zdne في ٢٢ أكتوبر ٢٠١٣

نعم ، هذا هو بالضبط AST الذي كنت أفكر فيه.

davidmc24 picture davidmc24 في ٢٢ أكتوبر ٢٠١٣

بالإضافة إلى ذلك ، أضف بناء جملة إضافيًا للأصول الخارجية المراد تضمينها (وليس مجرد ارتباط مرجعي) بواسطة Drafter apiaryio / snowcrash # 57

:[file.json](path/to/file.json)

أو

=[file.json](path/to/file.json)

بدلاً من ذلك ، يمكنك استخدام Mardkown _اسم الارتباط الضمني_:

:[path/to/file.json]()

أو

=[path/to/file.json]()
zdne picture zdne في ٣١ يناير ٢٠١٤
👍3

أهلا،
إليك حالة استخدام أخرى لوجود روابط خارجية: أود ربط تعريفات / أوصاف السمات في API بتعريفها الخاص في مسردنا الرئيسي الذي تستخدمه جميع الوثائق. أعتقد أن هذا يفتح الباب أمام تحديث جميع الوثائق ومزامنتها. خلاف ذلك ، سأضطر إلى تحديث مستند API. بشكل منفصل ، مما يترك مجالًا لتعريف عدم المزامنة.

angie2014 picture angie2014 في ٢٨ مايو ٢٠١٤

Markdown عبارة عن عائلة مقترنة بشكل غير مريح من الامتدادات المتوافقة في الغالب ، لذلك لست متأكدًا ، ولكن الحالة الوحيدة التي يمكنني التفكير فيها حيث تعني البنية الشبيهة بالرابط في الواقع "تضمين وليس مرجع" هي بنية الصورة (باستخدام ! sigil) : ![Alt text](/path/to/image.jpg "Optional Title") ، وهو جزء من مواصفات Gruber

jrep picture jrep في ٣٠ مايو ٢٠١٤

نقطة جيدة @ jrep !

ألن يكون من الأفضل التوافق ، ما عليك سوى استخدام علامة سيجيل جديدة على الصيغة الموجودة بخلاف ذلك؟

هذا هو هدفي.

وفقًا لما يلي Gruber ، يجب أن يحقق نفس الهدف:

[label](path/to/image.png)

[alt text][label2]
[label2]: path/to/image.png

[label3][]
[label3]: path/to/image.png

حيث لا يتواجد label و alt text و label3 نظريًا ، لكن لا تظهر العناصر بعد العرض.

اعتقد وجهة نظري مع

=[path/to/file.json]()

يجب ان يكون

=[path/to/file.json][]

حيث يكون العنوان هو عنوان URL الفعلي ، لذا فإن التعريف الكامل المناسب (لذلك يتم عرض العلامة التجارية بشكل صحيح) سيكون:

=[path/to/file.json][]
[path/to/file.json]: path/to/file.json

من الواضح أن كتابة:

[path/to/file.json]: path/to/file.json

السؤال هو - هل يجب أن يفترض المحلل اللغوي ضمنيًا هذا (تحديد التسمية)؟ أم يجب علينا فقط أن نطلب من مؤلفي المخططات استخدام بناء جملة [alt text](URL) ؟

zdne picture zdne في ٢ يونيو ٢٠١٤

ألا يمكننا استخدام جزء alt / label فقط لوصف ماهية الأصل حتى يكون الرابط مقروءًا من قبل الإنسان؟ يبدو أن كتابة شيء مثل =[file.json](path/to/file.json) مملة بلا داع ، ولكن يبدو لي أن =[Schema for notes](path/to/file.json) جيد - تشجيع كتاب المخططات على جعل المخططات أقل تشفيرًا للقراء. في الواقع ، يمكن أن تكون الأصول مفقودة أو قد يكون من غير الواضح أحيانًا ما هو المرتبط على وجه التحديد. تم اختراع سمات alt على الصور بالضبط لهذه الحالة على ما أعتقد.

إذا أراد شخص ما تجاوز هذا وتجاهل أفضل ممارسة لوصف الأصول بهذه الطريقة ، فيمكنه دائمًا وضع نص وهمي هناك (مثل file.json ).

لقد استخدمت بناء الجملة = كمثال فقط ، ينطبق الأمر نفسه على ! .

honzajavorek picture honzajavorek في ٢ يونيو ٢٠١٤

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

إذا اتفقنا على هذا ، يبقى سؤالان فقط:

  1. ما سيجيل للاستخدام
  2. أسلوب Whet الذي سنستخدمه في الأمثلة / البرنامج التعليمي

لاحظ أنه في رأيي تسمية مثل Schema for notes in

=[Schema for notes](path/to/file.json)

هو مزدوج أيضًا لأنه في أغلب الأحيان ستستخدمه في قسم مخطط لموارد Notes ...

على سبيل المثال:

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + Schema
        =[Schema for Notes](path/to/file.json)

أفكار؟

zdne picture zdne في ٢ يونيو ٢٠١٤

أنا جميعًا أدعم جميع المتغيرات القياسية ، لكن هذا:

= [المسار / إلى / file.json] []
[المسار / إلى / file.json]: المسار / إلى / file.json

... ليس كيف أفهم تعريف Gruber. بدلاً من ذلك ، أتفق مع honzajavorek: الأشياء الموجودة في [] الأول هي بطريقة ما علامة يمكن قراءتها من قبل الإنسان ، وليست نسخة مكررة ومرهقة من نص الرابط. لذلك ، في حين يبدو أن تضمين مسار هناك يبدو صحيحًا من الناحية التركيبية ، إلا أنه (أ) غريب و (ب) غير مفيد.

إذا كان القصد هو "أي نموذج ارتباط صالح لـ Gruber ، مع علامة سيجيل جديدة" ، فأنا أحب ذلك الدلالي ولكني أقترح مثالًا أقل إثارة للدهشة (من النوع الذي اقترحه honzajavorek).

jrep picture jrep في ٣ يونيو ٢٠١٤

honzajavorekjrep أوافق.

zdne picture zdne في ٣ يونيو ٢٠١٤

أعتقد أنه من الصعب مقارنة تضمين الأصول بالنماذج الحالية للصور أو الروابط. أليس في الواقع مزيج من هذين معًا؟

تكمن مشكلة تشبيه تركيب الصورة في أنه في عالم الصور ، تعتبر النصوص البديلة مهمة ، وعادةً لا تكون مكررة في سياق معين ولا يريد أحد أن يكتب فعليًا ![img.jpg](/path/to/img.jpg) - فقط أنظمة إدارة المحتوى و "كسول" يفعل الناس هذا. طلب النص البديل هو تعليم عادة جيدة.

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

[Google](http://www.google.com) مقابل ...

  • <http://www.google.com> ( Gruber )
  • http://www.google.com (واقع تخفيض السعر اليوم ، على ما أعتقد)

إذا احتجنا إلى شيء هجين ، فلنسميه "بناء جملة الارتباط التلقائي للصور" ، ونريد الالتزام بـ Gruber قدر الإمكان ، فنحن نريد شيئًا مثل التالي:

  • =[Alternative text about assets](/dev/null) ← كل شخص يعرف هذا ، يجب أن يكون هذا في الأمثلة (_ إنها مثل الصور ، منطقية! _ ظهرت في رؤوس الناس)
  • =[Alternative text about assets][id] ← لتضمين نفس الأصل في أماكن متعددة
  • =</dev/null> أو <=/dev/null> ← بناء جملة الارتباط التلقائي (_... كيف سيبدو بناء جملة الارتباط التلقائي للصور؟ _) ، لا أحد يعرف إصدار Gruber للربط التلقائي (لأن الروابط يتم تحويلها تلقائيًا في كل مكان ، حتى بدون < s و > s) ، ولكن في حالة عدم حاجتهم حقًا إلى النص البديل وكانوا منزعجين منه ، يمكن للأشخاص تعلم استخدام هذا

مرة أخرى ، باستخدام = كمثال فقط. في رأيي ، ستكون هذه الحلول الأكثر قابلية للقراءة و / أو على الأقل حلول Gruber-ish. على سبيل المثال ، أنا أعتبر

[label3][]
[label3]: path/to/image.png

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

honzajavorek picture honzajavorek في ٣ يونيو ٢٠١٤

zdne : بالنسبة إلى sigil: لا أهتم كثيرًا ، لكن = الذي نستخدمه جميعًا يبدو جيدًا.

zdne : أقر بأن النص الأكثر احتمالاً =[IN HERE](schema.json) زائد عن الحاجة لأي استخدام مخطط يمكنني التفكير فيه. فقط عصف ذهني ، هنا ، لكن ماذا لو استفدنا من هذا التكرار لتبسيط القواعد؟ هذا هو استبدال

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + Schema
        =[Schema for Notes](path/to/file.json)

مع

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + =[Schema for Notes](path/to/file.json)

honzajavorek : هل تقترح فعلاً أن مخطط يسمح /

أنا لا أستخدم "روابط مرجعية" أبدًا ، لكنني لن أعترض على قيام Blueprint بنقلها إلى الأمام.

jrep picture jrep في ٣ يونيو ٢٠١٤

jrep لقد استخدمت /dev/null كعنصر نائب :)

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

honzajavorek picture honzajavorek في ٣ يونيو ٢٠١٤

jrep أحب ذلك.

أخذها إلى أبعد من ذلك

# Notes [/notes]
## GET 
+ Response 200
    + =[Body](path/to/body.json)
    + =[Schema](path/to/schema.json)
zdne picture zdne في ٤ يونيو ٢٠١٤

ستكون القدرة على تقسيم الملف إلى ملفات منفصلة ثم استيرادها فيها مفيدة جدًا لواجهات برمجة التطبيقات الطويلة.

في الفترة الفاصلة ، أدير مشروع المخطط الخاص بي مع الناخر. أستخدم grunt-import ويتكون ملفي index.source.apib في الغالب من <strong i="7">@import</strong> "/include/section.apib";

ثم كل ما أفعله هو تشغيل grunt watch وبمجرد أن أقوم بحفظ أي ملف ، سيقوم grunt بإعادة تجميع ملف index.source.apib في "index.apib" - والذي تتم مشاهدته أيضًا بواسطة aglio ، تحديث المتصفح الخاص بي إلى أرني العرض في الوقت الفعلي.

يستغرق الإعداد 5 دقائق ، لكنه يجعل الحياة أجمل بكثير! : +1:

alexborisov picture alexborisov في ٣٠ أغسطس ٢٠١٤

alexborisov هذا أنيق جدا! شكرا على المشاركة. كما قلت (في مكان آخر) - لقد بدأنا العمل على أداة تسخير المحلل اللغوي التي يجب أن تهتم بهذا الأمر في النهاية.

أيضًا ، لما تستحقه ، إليك نص برمجي يؤلف مخططات متعددة في واحدة وينشرها باستخدام جوهرة عميل Apiary https://gist.github.com/danvine/11087404

zdne picture zdne في ١ سبتمبر ٢٠١٤

alexborisov ، هذا عمل ذكي حقًا! هل تعرف (أو أي شخص يشاهد هذه المشكلة) ما إذا كان هناك نظير لشركة Gulp للاستيراد الناخر؟ لقد عثرت على مستندات Gulp على جميع مستندات JS و html المستهدفة.

skawaguchi picture skawaguchi في ٢٤ نوفمبر ٢٠١٤

skawaguchi يمكنك استخدام -file-include وإنشاء مهمة gulp لمشاهدة json وبناء واجهة برمجة التطبيقات. الجانب السلبي الوحيد هو أنه يجب أن يكون لديك api.source.md لإنشاء api.md الخاص بك ، ولكن IMO هو ثمن زهيد يجب دفعه.

ghost picture ghost في ٢٤ فبراير ٢٠١٥

أيضًا لمعرفة ما يستحق التحقق من هرقل https://github.com/jamesramsay/hercule

zdne picture zdne في ٢٥ فبراير ٢٠١٥

شكرا zdne للإشارة . واجهت تحديات مماثلة عند كتابة وثائق API وكنا نستخدم Hercule داخليًا خلال الأشهر الثلاثة الماضية.

يستخدم Hercule نموذج {{filename.md}} بسيطًا للتضمين.

لدينا عدد من سياقات API لأنواع مختلفة من مستهلكي API الذين لديهم موارد متطابقة تقريبًا وكنا حريصين على تقليل الازدواجية بين المستندات المختلفة. وبالتالي ، قمنا أيضًا بتوسيع هذا النحو لدعم:

{{entity.json links:role-links.json}}

{
  "id": 123,
  "name": "example",
  "links": {
    {{links}}
  }
}

يمكن عندئذٍ أن يحتوي العنصر النائب {{links}} على الملف الهدف المحدد بواسطة أحد ملفاته الأصلية. لقد وجدنا هذا مفيدًا للمخططات الكبيرة المتشابهة تقريبًا.

jamesramsay picture jamesramsay في ٢٦ فبراير ٢٠١٥

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

أنا فقط أتساءل لماذا استخدم بناء جملة {{link}} بدلاً من Markdown الخاص بـ Markdown [<placeholder>](link) ؟ كما نوقش أعلاه. على سبيل المثال:

=[gist](gist.apib)

أو

:[gist](gist.apib)

سيعمل بشكل مشابه ، سيعرض بشكل معقول كتخفيض السعر ، لذلك ستكون قادرًا على التنقل عبر الروابط ، ويمكنك استخدام صياغة أكثر ثراءً مثل [placeholder][] مع خيارات رابط "[placeholder] ...

zdne picture zdne في ٢٧ فبراير ٢٠١٥

zdne هذا اقتراح رائع حقًا! سيء للغاية لم أر هذا الموضوع منذ 6 أشهر.

استند بناء الجملة {{link}} صيغة التحويل لـ MultiMarkdown 4 . لقد أدت الحيلة ولم أخترع صيغة جديدة.

في ذلك الوقت ، نظرت أيضًا إلى تطبيق Marked ( <<[link] ) واثنين من برامج التحويل البرمجي Markdown الأخرى.

مع ميزة القدرة على النقر فوق الروابط عند عرض الوثائق المصدر في Github وتحسين التناسق مع إحساس Markdown ، فقد قمت بتحديث هذه الوحدة لاستخدام :[gist](gist.apib) . إذا كان أي شخص يرغب في أخذها في جولة ، فهي في NPM.

jamesramsay picture jamesramsay في ٤ مارس ٢٠١٥

مرحبًا يا رفاق ، أنا أستخدم API Blueprint مع aglio لمشروعنا الداخلي ، وبما أن API Blueprint لا يدعم الملف بما في ذلك حاليًا ، فإن aglio ينفذ واحدًا باستخدام بناء الجملة <!-- include(filename.json) --> ، بفضل هذه الميزة يمكننا تقسيم الطلب / الرد بيانات JSON من مستند API بوضوح ، ولكن عندما ننظم ملفات بيانات JSON المنفصلة ، نجد أنها لا تزال تفتقر إلى الطريقة المناسبة لإعادة استخدام الجزء نفسه ، على سبيل المثال ، لدينا user_model.json :

{
    "username": "alice",
    "comments": [
        {
            "id": 1,
            "content": "hello"
        }
    ]
}

و comment_model.json :

{
    "id": 1,
    "content": "hello"
}

جزء التعليق في user_model.json هو ويجب أن يكون دائمًا هو نفسه comment_model.json ، إذا كانت هناك آلية تسمح لملف JSON بتضمين بعضها البعض ، فسيكون من السهل جدًا الحفاظ على تناسقها ، لذلك أنه في حالة تغيير نموذج الثناء ، لا نحتاج إلى تغييره في كل مكان.

أعتبره لبعض الوقت وأحاول إنشاء بناء جملة لدعم ملف JSON بما في ذلك ، هنا جهودي ،
قم بتضمين sytanx مع تطبيق Python: https://github.com/reorx/json_include

سيكون بناء الجملة كما في الحالة السابقة:

{
    "username": "alice",
    "comments": [
        {
            "...": "include(commend_model.json)"
        }
    ]
}

باستخدام { "...": "include(commend_model.json)"} لتمثيل ملف بما في ذلك commend_model.json .

إنها ليست حالة خاصة لـ API Blueprint ، ولكنها شيء عام إلى حد ما ، لمحاولة التفكير في JSON نفسها مع إمكانية التضمين ، والتي أعتقد أنه يمكن استخدامها أيضًا في مخطط API.

يرجى إلقاء نظرة وإعطاء بعض الاقتراحات ، حاليًا هذا json-include يعمل بشكل جيد في بعض

reorx picture reorx في ٢٨ أبريل ٢٠١٥

يا reorx ! شكرا لتقاسم الفكرة. لقد أطلقنا مؤخرًا ( تجريبيًا ) من

باستخدام الأمثلة الخاصة بك ، يعمل على النحو التالي:

# Data Structures

## User 
- username: alice
- comments (array[Comment])

## Comment
- id: 1
- content: hello

وبعد ذلك يمكنك طلب عرضه كـ JSON:

# Resource [/r]
## Retrieve [GET]
+ Response (application/json)
    + Attributes (User)

ماذا تعتقد؟ هل سيساعدك هذا؟

zdne picture zdne في ٢٨ أبريل ٢٠١٥

هل هذه الميزة في أي مكان في خط الأنابيب؟ سيكون لطيفا جدا بالنسبة لنا.
نحن نستخدم Blueprint لوصف الطرق ، ولكن لدينا مخطط JSON مستضاف بشكل منفصل. يتعين علينا تضمين المخطط كروابط في أوصاف الطريقة ، نظرًا لأنه غير مدعوم ضمن عنصر الطلب / الاستجابة حاليًا.
في الواقع ، سيكون أفضل شيء هو إذا تمكنا من "تضمين" صفحة ويب مخطط JSON باستخدام رابط ضمن عنصر الطلب / الاستجابة ، ولكن يجب أن يتم تحميلها ببطء ، لتجنب القيام بالمئات من التضمينات عند تحميل صفحة التوثيق.

jonathancrosmer picture jonathancrosmer في ٢٠ أغسطس ٢٠١٥

أعتقد أن حقيقة أنه لا يمكنك تضمين مراجع خارجية لأمثلة على هيئة الطلبات / الاستجابة وملفات مخطط التعريف هي أحد الجوانب السلبية الكبيرة التي يمتلكها Blueprint فيما يتعلق بلغات تعريف API الأخرى.

mariusor picture mariusor في ١٧ نوفمبر ٢٠١٥

+1

moon0326 picture moon0326 في ٢١ نوفمبر ٢٠١٥

jonathancrosmerlpbm @ moon0326

تحقق من https://github.com/jamesramsay/hercule بشكل خاص

https://github.com/jamesramsay/hercule/blob/master/examples/api-blueprint/gist-fox.apib

و

https://github.com/jamesramsay/hercule/blob/master/examples/api-blueprint/blueprint/gists.md

هل هذا يعمل من أجلك؟

zdne picture zdne في ٢٤ نوفمبر ٢٠١٥

zdne أنا لا

هذان المثالان لا يظهران الكثير. ما أنا أبحث في؟

moon0326 picture moon0326 في ٢٤ نوفمبر ٢٠١٥

zdne : نعم ، طالما أنه يسمح بإدراج أي نوع من الموارد الخارجية ، سواء كان .md / .apib أو xml ، فهذا جيد.

هل هو شيء سينفذه Apiary ، أم أن رسالتك تنصحنا باستخدام hercule قبل الالتزام بالمنحل؟

mariusor picture mariusor في ٢٤ نوفمبر ٢٠١٥

في الماضي ، أعددت قائمة بالحلول لتقسيم المخطط إلى ملفات متعددة (واستخدام الأصول الخارجية): https://gist.github.com/zdne/137396a1c2d45f75b306

قامjamesramsay بتجميع أداة

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

ومع ذلك ، إذا كنت لا تعتمد على التحرير داخل Apiary ، فيمكنك استخدام Hercule اليوم للحصول على معظم هذه الوظيفة.

هل هو شيء سوف ينفذه Apiary؟

نريد تنفيذ بعض التضمين بناءً على بناء الجملة :[](url) ، نعم. المهم هنا هو محرر Apiary وتطبيق "نظام ملفات". حتى ذلك الحين ، يجب عليك استخدام Hercule ودفع الملف المتسلسل إلى Apiary.

هل هذا يوضح؟

zdne picture zdne في ٢٥ نوفمبر ٢٠١٥
👍1

المهم هنا هو محرر Apiary وتنفيذ "نظام ملفات"

ربما يمكنك التحايل على ذلك باستخدام عناوين URL؟

mariusor picture mariusor في ٢٥ نوفمبر ٢٠١٥

لجلب المستندات ربما نعم ولكن ليس للتحرير.

zdne picture zdne في ٢٥ نوفمبر ٢٠١٥

حاليًا لدينا مخطط Apiary مخزّن في مستودع git الخاص بنا والمتصل بـ Apiary. يحتوي المخطط على العديد من الروابط إلى خادم داخلي يستضيف مخطط JSON الخاص بنا.
أفترض أنه مع هذا الحل سيكون لدينا ملف Markdown أصلي ، ثم استخدم خطاف Git أو أي شيء لتشغيل التحويل وإلزام النتيجة كمخطط المزامنة. يبدو أنه يمكن أن يعمل ؛ قليل من المتاعب لإعداد عملية التضمين ، ولكن سيكون الأمر سلسًا إذا نجحت ، لذلك سأبحث في الأمر. شكرا!

jonathancrosmer picture jonathancrosmer في ٢٥ نوفمبر ٢٠١٥

يدعم lpbm Hercule كلاً من

jonathancrosmer على الفور - نفعل شيئًا مشابهًا باستخدام Jenkins في بيئة CI الداخلية. في Adslot ، كلما تم دفع التزام إلى أي فرع ، جنبًا إلى جنب مع اختبارات الوحدة ، نقوم بتجميع مخطط API مع Hercule ، ثم نمرره إلى dredd. إذا كان كل شيء يمر ، كجزء من مهمة النشر ، يمكننا اختياريًا الدفع إلى Apiary. لقد دفعنا في الأصل مباشرة إلى Apiary بمجرد إجراء التغييرات على مستندات API ، لكننا وجدنا أن هذا تسبب في بعض الأحيان في حدوث مشكلات عندما كنا نعمل على إصدارات أكبر مع مفاتيح تبديل الميزات وما شابه ، وبالتالي ننتشر الآن جنبًا إلى جنب مع التطبيق.

jamesramsay picture jamesramsay في ٢٥ نوفمبر ٢٠١٥

ماذا عن مجرد السماح بتحديد محددات مواقع المعلومات (URIs) العادية؟ يمكن أن يقرر العارض ما إذا كان سيتم عرض URI إلى ارتباط أو تضمين محتوياته في إخراج التوثيق. هذا يوفر علينا أيضًا عناء الاضطرار إلى التعامل مع نكهات Markdown المختلفة.

bartfeenstra picture bartfeenstra في ٢٠ مايو ٢٠١٦

ماذا عن مجرد السماح بتحديد محددات مواقع المعلومات (URIs) العادية؟

يجب أن يكون هذا هو الحال. [label](URI) للتحويل وكذلك العرض بشكل جيد. الاختلاف هو أننا نحتاج إلى تحديد ما إذا كان لأداة التحويل ومن ثم :[label](URI)

zdne picture zdne في ٩ يونيو ٢٠١٦

أهلا،

هل هناك أي أخبار عن هذا؟
أعتقد أنه يجب فصل المخطط والأمثلة عن الجسم الرئيسي لوثائق API ، بحيث يمكن استخدامها بواسطة الخادم و / أو العميل للتحقق من الصحة واختبارات الوحدة. الروابط على ما يرام.

هتافات،

تاماس

smil2k picture smil2k في ١١ ديسمبر ٢٠١٧

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

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

clucasalcantara picture clucasalcantara في ٥ أغسطس ٢٠١٨
هل كانت هذه الصفحة مفيدة؟
0 / 5 - 0 التقييمات

القضايا ذات الصلة

pete001 picture pete001  ·  6تعليقات
jrep picture jrep  ·  10تعليقات
fh-thudson picture fh-thudson  ·  3تعليقات
teja5429 picture teja5429  ·  9تعليقات
bazo picture bazo  ·  8تعليقات