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 您的标题##Authentication 是组描述的一部分，而不是资源描述的一部分。 一旦您定义了组中的第一个端点，您就结束了组描述并从资源端点开始。

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 编辑器中的警告/问题，你会在那里看到警告。 根据规范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 根本不支持第三级嵌套 - 请参阅上面评论中链接的规范文件。

所以我的问题没有解决方案？