Api-blueprint: Definir mais de uma seção dentro de um grupo

@ spark-ftw Infelizmente, o primeiro título Authentication está apenas anexado à descrição do grupo de recursos Print . A descrição é mostrada diretamente abaixo do título do recurso e, em seguida, todos os recursos são listados abaixo.

Eu sugiro refatorar isso um pouco para agrupar diferentes grupos de recursos da seguinte maneira:

• Grupo de Autenticação
  
  
  
  • Coleção de recursos do usuário
  
  
  • Listar todos os usuários
  
  
  • Registre uma nova conta de usuário
  
  
• Grupo de impressão
  
  
  
  • ...
  
  

Como você pode ver na imagem em anexo, eu já tenho um grupo - é o "Grupo de impressão" e os "Autenticação" e "Imprimir documentos" são filhos do "Grupo de impressão" então sua solução não funciona para mim. Você tem outra idéia?

Obrigado

@ spark-ftw O que @kylef quis dizer está correto. Você não pode ter uma descrição de redução aleatória dentro de um grupo de recursos ( Group Print ), uma vez que você já descreveu um recurso ( User Collection ).

Você pode fazer algo assim. (que é o que @kylef propôs).

# 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 : Atualizado o comentário depois de corrigir um pequeno erro.

Isso não me ajuda, pois preciso de várias seções dentro de cada seção, como:

• Seção de impressão

- Grupo de autenticação

--- Coleção do usuário

--- Coleção Auth

- Grupo de documentos

--- Imprimir coleção de documentos

--- Salvar coleção de documentos

• Seção de direção

- Grupo de autenticação

--- Coleção do usuário

--- Coleção Auth

- Grupo de documentos

--- Imprimir coleção de documentos

--- Salvar coleção de documentos

...

Obrigado

Alguma ideia?

@ spark-ftw adicionei !comments ao código abaixo. TL; DR Seu cabeçalho ## Autenticação faz parte da descrição do Grupo, não faz parte da descrição do Recurso. Depois de definir o primeiro ponto de extremidade em um grupo, você acabou de terminar a descrição do grupo e começou com pontos de extremidade de recurso.

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, então como posso conseguir a estrutura que desejo?

@ spark-ftw Você não pode ter o título que deseja se insistir na estrutura da árvore. Você ainda pode usar vários grupos como:

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

Sinto muito, mas não vejo outra solução que use mais grupos. Mas você se beneficiará com isso - porque a navegação na documentação do Apiário faz uso desses grupos. Portanto, é uma solução ganha-ganha.

Por favor, veja minha solicitação novamente:

-Seção de impressão

- Grupo de autenticação

--- Coleção do usuário

--- Coleção Auth

- Grupo de documentos

--- Imprimir coleção de documentos

--- Salvar coleção de documentos

Seção de direção

- Grupo de autenticação

--- Coleção do usuário

--- Coleção Auth

- Grupo de documentos

--- Imprimir coleção de documentos

--- Salvar coleção de documentos

Exceto o Print, também preciso do produto Drive. Isso é outra coisa (então eu preciso de outro nível de hierarquia)

A propósito, o markdown suporta isso, apenas o apiário tem um problema para analisá-lo ...

@ spark-ftw Não é que o Apiary tenha um problema - é que a descrição entre os pontos de extremidade do recurso não pode estar lá - se você olhar em Avisos / Problemas no Editor do Apiário, verá um Aviso lá. De acordo com a especificação https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def -section-structure - uma seção Group contém estas partes: Nome do grupo , Descrição do grupo, Recursos do grupo. Nada como outra descrição intermediária.

Se comparar Markdown vs. API Blueprint - você terminará com uma estrutura linear, não em árvore.

@ spark-ftw Observe que a palavra-chave Group é usada para denotar o início do novo Section .
O API Blueprint não oferece suporte a aninhamento de terceiro nível - consulte o arquivo de especificação vinculado no comentário acima.

Portanto, nenhuma solução para o meu problema?