Api-blueprint: グループ内に複数のセクションを設定する

@ spark-ftw残念ながら、最初の見出しAuthenticationは、 Printリソースグループの説明に添付されています。 説明はリソース見出しのすぐ下に表示され、次にすべてのリソースが以下にリストされます。

次のように、これを少しリファクタリングして、さまざまなリソースグループをグループ化することをお勧めします。

• 認証グループ
  
  
  
  • ユーザーリソースの収集
  
  
  • すべてのユーザーを一覧表示
  
  
  • 新しいユーザーアカウントを登録する
  
  
• プリントグループ
  
  
  
  • ..。
  
  

添付の画像でわかるように、私はすでにグループを持っています-それは「印刷グループ」であり、「認証」と「印刷ドキュメント」は「印刷グループ」の子であるため、ソリューションは機能しません。 別のアイデアはありますか？

ありがとう

@ spark-ftw @ kylefの意味は正しいです。 リソース（ User Collection ）を既に記述した後は、リソースグループ（ Group Print ）内にランダムなマークダウン記述を含めることはできません。

あなたはこのようなことをすることができます。 （これは@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のドキュメントのナビゲーションではこれらのグループが使用されるため、これでメリットが得られます。 つまり、これは双方にメリットのあるソリューションです。

もう一度私のリクエストをご覧ください：

-印刷セクション

-認証グループ

---ユーザーコレクション

---認証コレクション

-ドキュメントグループ

---ドキュメントコレクションを印刷します

---ドキュメントコレクションを保存します

ドライブセクション

-認証グループ

---ユーザーコレクション

---認証コレクション

-ドキュメントグループ

---ドキュメントコレクションを印刷します

---ドキュメントコレクションを保存します

印刷以外に、ドライブ製品も必要です。 これは別のものです（したがって、別の階層レベルが必要です）

ちなみに、マークダウンはこれをサポートしています、養蜂場だけがそれを解析するのに問題があります...

@ spark-ftw Apiaryに問題があるわけではありません。つまり、リソースエンドポイント間の説明が許可されていないということです。ApiaryEditorで警告/問題を調べると、そこに警告が表示されます。 仕様によるとhttps://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-section-structure-$＃$ Groupセクションには次の部分が含まれています：グループ名、グループの説明、グループリソース。 間に別の説明として何もありません。

MarkdownとAPIブループリントを比較すると、代わりに線形の非ツリー構造で終わります。

@ spark-ftwキーワードGroupは、新しいSection開始を示すために使用されることに注意してください。
API Blueprintは、第3レベルのネストをまったくサポートしていません。上記のコメントにリンクされている仕様ファイルを参照してください。

だから私の問題の解決策はありませんか？