Api-blueprint: Establecer más de una sección dentro de un grupo

@ spark-ftw Desafortunadamente, el primer encabezado Authentication se acaba de adjuntar a la descripción del grupo de recursos Print . La descripción se muestra directamente debajo del encabezado del recurso y luego todos los recursos se enumeran a continuación.

Sugeriría refactorizar esto ligeramente para agrupar diferentes grupos de recursos de la siguiente manera:

• Grupo de autenticación
  
  
  
  • Colección de recursos de usuario
  
  
  • Lista de todos los usuarios
  
  
  • Registrar nueva cuenta de usuario
  
  
• Grupo de impresión
  
  
  
  • ...
  
  

Como puede ver en la imagen adjunta, ya tengo un grupo: es "Grupo de impresión" y "Autenticación" y "Documentos de impresión" son elementos secundarios del "Grupo de impresión", por lo que su solución no me funciona. ¿Tienes otra idea?

Gracias

@ spark-ftw Lo que @kylef quiso decir es correcto. No puede tener una descripción de rebaja aleatoria dentro de un grupo de recursos ( Group Print ) una vez que ya ha descrito un recurso ( User Collection ).

Puedes hacer algo como esto. (que es lo que propuso @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

            {}

EDITAR : actualizado el comentario después de corregir un pequeño error.

Esto no me ayuda, ya que necesito varias secciones dentro de cada sección así:

• Sección de impresión

- Grupo de autenticación

--- Colección de usuarios

--- Auth colección

- Grupo de documentos

--- Imprimir colección de documentos

--- Guardar colección de documentos

• Sección de conducción

- Grupo de autenticación

--- Colección de usuarios

--- Auth colección

- Grupo de documentos

--- Imprimir colección de documentos

--- Guardar colección de documentos

...

Gracias

¿Algunas ideas?

@ spark-ftw He agregado algo de !comments en el siguiente código. TL; DR Su encabezado ## La autenticación es parte de la descripción del grupo, no parte de la descripción del recurso. Una vez que defina el primer punto final en un grupo, acaba de finalizar la descripción del grupo y ha comenzado con los puntos finales de recursos.

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

Bien, entonces, ¿cómo puedo lograr la estructura que quiero?

@ spark-ftw No puede tener el encabezado que desea si insiste en la estructura de árbol. Todavía puede utilizar varios grupos como:

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

Lo siento, pero no veo otra solución que usar más Grupos. Pero se beneficiará con eso, porque la navegación en la documentación en Apiary hace uso de estos Grupos. Por tanto, es una solución en la que todos ganan.

Por favor, vea mi solicitud nuevamente:

-Sección de impresión

- Grupo de autenticación

--- Colección de usuarios

--- Auth colección

- Grupo de documentos

--- Imprimir colección de documentos

--- Guardar colección de documentos

Sección de conducción

- Grupo de autenticación

--- Colección de usuarios

--- Auth colección

- Grupo de documentos

--- Imprimir colección de documentos

--- Guardar colección de documentos

Excepto Print, también necesito el producto Drive. Esto es otra cosa (entonces necesito otro nivel de jerarquía)

Por cierto, la rebaja es compatible con esto, solo el colmenar tiene problemas para analizarlo ...

@ spark-ftw No es que Apiary tenga un problema, es que no se permite que la descripción entre los puntos finales de recursos esté allí, si miras las advertencias / problemas en el editor de Apiary, verás una advertencia allí. De acuerdo con la especificación https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def -section-structure - una sección Group contiene estas partes: Nombre del grupo , Descripción del grupo, Recursos del grupo. Nada como otra descripción intermedia.

Si compara Markdown versus API Blueprint, terminará con una estructura lineal, sin árbol.

@ spark-ftw Tenga en cuenta que la palabra clave Group se utiliza para indicar el inicio de un nuevo Section .
API Blueprint no admite el anidamiento de tercer nivel en absoluto; consulte el archivo de especificación vinculado en el comentario anterior.

Entonces, ¿no hay solución para mi problema?