Api-blueprint: Установка более одного раздела внутри группы

@ spark-ftw К сожалению, первый заголовок Authentication просто прикреплен к описанию группы ресурсов Print . Описание отображается непосредственно под заголовком ресурса, а затем все ресурсы перечислены ниже.

Я бы предложил немного реорганизовать это, чтобы сгруппировать разные группы ресурсов следующим образом:

• Группа аутентификации
  
  
  
  • Коллекция пользовательских ресурсов
  
  
  • Список всех пользователей
  
  
  • Зарегистрируйте новую учетную запись пользователя
  
  
• Группа печати
  
  
  
  • ...
  
  

Как вы можете видеть на прикрепленном изображении, у меня уже есть группа - это «Группа печати», а «Аутентификация» и «Документы печати» являются дочерними элементами «Группы печати», поэтому ваше решение не работает для меня. Есть ли у вас другая идея?

Спасибо

@ spark-ftw То, что имел в виду 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

            {}

РЕДАКТИРОВАТЬ : обновлен комментарий после исправления небольшой ошибки.

Это мне не помогает, так как мне нужно несколько разделов внутри каждого раздела, например:

• Раздел печати

- Группа авторизации

--- Коллекция пользователей

--- Коллекция Auth

- Группа документов

--- Распечатать коллекцию документов

--- Сохранить коллекцию документов

• Секция привода

- Группа авторизации

--- Коллекция пользователей

--- Коллекция аутентификации

- Группа документов

--- Распечатать коллекцию документов

--- Сохранить коллекцию документов

...

Спасибо

Любые идеи?

@ 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 используются эти группы. Так что это беспроигрышное решение.

Пожалуйста, посмотрите мой запрос еще раз:

-Печать раздел

- Группа авторизации

--- Коллекция пользователей

--- Коллекция аутентификации

- Группа документов

--- Распечатать коллекцию документов

--- Сохранить коллекцию документов

Секция привода

- Группа авторизации

--- Коллекция пользователей

--- Коллекция аутентификации

- Группа документов

--- Распечатать коллекцию документов

--- Сохранить коллекцию документов

Кроме печати, мне также нужен Диск. Это что-то еще (так что мне нужен другой уровень иерархии)

Кстати, уценка это поддерживает, только у пасеки проблема с парсингом ...

@ spark-ftw Проблема не в том, что у пасеки - проблема в том, что описание между конечными точками ресурсов не может быть там - если вы посмотрите предупреждения / проблемы в редакторе пасеки, вы увидите там предупреждение. Согласно спецификации https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def -section-structure - раздел Group содержит следующие части: Имя группы , Описание группы, Ресурсы группы. Ничего, как еще одно промежуточное описание.

Если сравнивать Markdown и API Blueprint - вместо этого вы получите линейную, не древовидную структуру.

@ spark-ftw Обратите внимание, что ключевое слово Group используется для обозначения начала нового Section .
API Blueprint вообще не поддерживает вложение третьего уровня - см. Файл спецификации, указанный в комментарии выше.

Так нет решения моей проблемы?