Api-blueprint: وضع أكثر من قسم داخل المجموعة

@ spark-ftw لسوء الحظ ، تم إرفاق العنوان الأول Authentication للتو بوصف مجموعة الموارد Print . يتم عرض الوصف مباشرة أسفل عنوان المورد ثم يتم سرد كافة الموارد أدناه.

أقترح إعادة هيكلة هذا قليلاً لتجميع مجموعات موارد مختلفة على النحو التالي:

• مجموعة المصادقة
  
  
  
  • مجموعة موارد المستخدم
  
  
  • قائمة بجميع المستخدمين
  
  
  • تسجيل حساب مستخدم جديد
  
  
• مجموعة الطباعة
  
  
  
  • ...
  
  

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

شكرا

@ spark-ftw ما تعنيه @ kylef هو الصحيح. لا يمكنك الحصول على وصف تخفيض السعر العشوائي داخل مجموعة الموارد ( Group Print ) بمجرد وصف المورد بالفعل ( User Collection ).

يمكنك فعل شيء مثل هذا. (وهو ما اقترحه @ kylef ).

# Group Authentication

## Authentication
Resource related to user auth

## User collection [/users]

### List all users [GET]
+ Response 200 (application/json)

            {}

### Register new user account [POST]
+ Request (application/json)

            {}

+ Response 201

            {}

# Group Print

## Print docs
Resource related to prints

## Print collection [/print]

### List all users [GET]
+ Response 200 (application/json)

            {}

### Register new user account [POST]
+ Request (application/json)

            {}

+ Response 201

            {}

تحرير : تم تحديث التعليق بعد إصلاح خطأ صغير.

هذا لا يساعدني ، لأنني بحاجة إلى عدة أقسام داخل كل قسم مثل:

• قسم الطباعة

- مجموعة المصادقة

--- مجموعة المستخدم

--- مجموعة المصادقة

- مجموعة المستندات

- طباعة مجموعة المستندات

--- حفظ مجموعة المستندات

• قسم القيادة

- مجموعة المصادقة

--- مجموعة المستخدم

--- مجموعة المصادقة

- مجموعة المستندات

- طباعة مجموعة المستندات

--- حفظ مجموعة المستندات

...

شكرا

أيه أفكار؟

@ spark-ftw لقد أضفت بعض !comments إلى الكود أدناه. TL ؛ DR العنوان ## المصادقة جزء من وصف المجموعة وليست جزءًا من وصف المورد. بمجرد تحديد نقطة النهاية الأولى في المجموعة ، تكون قد أنهيت للتو وصف المجموعة وبدأت بنقاط نهاية المورد.

FORMAT: 1A
HOST: https://sample

# sampleapi
Sample API

! group definition starts here with name, and description following
# Group Print
Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum 

## Authentication <--- part of description above
Resource related to user auth <--- part of description above

! First endpoint definition starts here, group description ends here.
## User collection [/users]
### List all users [GET]
+ Response 200 (application/json)
        [...]

### Register new user account [POST]
+ Request (application/json)
            { ... }
+ Response 201
    + Headers
            Location: https://sample

## Print docs <-- this is not another endpoint / resource definition, but a description instead...
Resource related to prints <-- this is not another endpoint / resource definition, but a description instead...

! another resource endpoint is defined below, that is ok.
## Print collection [/print]
### List all users [GET]
+ Response 200 (application/json)
    [...]

حسنًا ، كيف يمكنني تحقيق الهيكل الذي أريده؟

@ spark-ftw لا يمكنك الحصول على العنوان الذي تريده إذا كنت تصر على هيكل الشجرة. لا يزال بإمكانك استخدام مجموعات متعددة على النحو التالي:

Group Print Authentication
  - User Collection
    - List all
    - Register new...
Group Print Docs
Group Drive Authentication
Group Drive Docs
...

أنا آسف ، لكنني لا أرى حلًا آخر لاستخدام المزيد من المجموعات. لكنك ستستفيد من ذلك - لأن التنقل في الوثائق في Apiary يستخدم هذه المجموعات. لذلك فهو حل يربح فيه الجميع.

يرجى الاطلاع على طلبي مرة أخرى:

- قسم الطباعة

- مجموعة المصادقة

--- مجموعة المستخدم

--- مجموعة المصادقة

- مجموعة المستندات

- طباعة مجموعة المستندات

--- حفظ مجموعة المستندات

قسم القيادة

- مجموعة المصادقة

--- مجموعة المستخدم

--- مجموعة المصادقة

- مجموعة المستندات

- طباعة مجموعة المستندات

--- حفظ مجموعة المستندات

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

بالمناسبة ، فإن تخفيض السعر يدعم هذا ، فقط المنحل لديه مشكلة في تحليله ...

@ spark-ftw لا يعني ذلك أن Apiary لديه مشكلة - إنها أن الوصف بين نقاط نهاية المورد غير مسموح بوجوده - إذا نظرت في التحذيرات / المشكلات في Apiary Editor ، فسترى تحذيرًا هناك. وفقًا للمواصفات https://github.com/apiaryio/api-blueprint/blob/master/API٪20Blueprint٪20Specification.md#def -section-structure - يحتوي قسم Group على هذه الأجزاء: اسم المجموعة ، وصف المجموعة ، موارد المجموعة. لا شيء بين وصف آخر.

في حالة مقارنة Markdown مقابل API Blueprint - ستنتهي ببنية خطية غير شجرية بدلاً من ذلك.

@ spark-ftw يرجى ملاحظة أن الكلمة الأساسية Group تُستخدم للإشارة إلى بداية Section .
مخطط API لا يدعم تداخل المستوى الثالث على الإطلاق - يرجى الاطلاع على ملف المواصفات المرتبط في التعليق أعلاه.

لذلك لا يوجد حل لمشكلتي؟