Api-blueprint: Setting more than one section inside a group

@spark-ftw Unfortunately the first heading Authentication is just attached to the description for the Print Resource group. The description is shown directly below the resource heading and then all of the resources are listed below.

I'd suggest refactoring this slightly to group different resource groups as follows:

• Authentication Group
  
  
  
  • User resource collection
  
  
  • List all users
  
  
  • Register new user account
  
  
• Print Group
  
  
  
  • ...
  
  

As you can see in the attached image, I already have a group - it is "Print group" and the "Authentication" and "Print docs" are children of "Print group" so your solution does not work for me. Do you have another idea?

Thanks

@spark-ftw What @kylef meant is correct. You cannot have random markdown description inside a resource group (Group Print) once you have already described a resource (User Collection).

You can do something like this. (which is what @kylef proposed).

# 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

            {}

EDIT: Updated the comment after fixing a small error.

This doesn't help me, since I need several sections inside each section like so:

• Print Section

-- Auth group

--- User collection

--- Auth collection

-- Docs group

--- Print docs collection

--- Save docs collection

• Drive Section

-- Auth group

--- User collection

--- Auth collection

-- Docs group

--- Print docs collection

--- Save docs collection

...

Thanks

Any ideas?

@spark-ftw I've added some !comments into the code below. TL;DR Your heading ##Authentication is part of Group description, not part of Resource description. Once you define first endpoint in a group, you've just ended the Group-description and started with Resource Endpoints.

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)
    [...]

OK, so how can I achieve the structure I want?

@spark-ftw You can't have the heading you want if you insist on the tree-structure. You can still use multiple-groups as:

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

I'm sorry, but I don't see another solution that to use more Groups. But you'll benefit with that - because navigation in the documentation in Apiary makes use of these Groups. So it is a win-win solution.

Please see my request again:

-Print Section

-- Auth group

--- User collection

--- Auth collection

-- Docs group

--- Print docs collection

--- Save docs collection

Drive Section

-- Auth group

--- User collection

--- Auth collection

-- Docs group

--- Print docs collection

--- Save docs collection

Except Print, I also need Drive product. This is something else (so I need another hierarchy level)

By the way, the markdown supports this, only apiary has a problem with parsing it...

@spark-ftw It's not that Apiary has a problem - it's that the description between Resource Endpoints is not allowed to be there - if you look into the Warnings / Issues in Apiary Editor, you'll see a Warning there. According to the specification https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-section-structure - a Group section contains these parts: Group Name, Group Description, Group Resources. Nothing as another description in-between.

If comparing Markdown vs. API Blueprint - you will end with a linear, non-tree structure instead.

@spark-ftw Please note that the keyword Group is used to denote start of new Section.
API Blueprint does not support third level nesting at all - please see the specification file linked in comment above.

So no solution for my problem?