Api-blueprint: Définir plus d'une section à l'intérieur d'un groupe

@spark-ftw Malheureusement, le premier titre Authentication est juste attaché à la description du groupe de ressources Print . La description est affichée directement sous le titre de la ressource, puis toutes les ressources sont répertoriées ci-dessous.

Je suggérerais de refactoriser légèrement cela pour regrouper différents groupes de ressources comme suit :

• Groupe d'authentification
  
  
  
  • Collecte de ressources utilisateur
  
  
  • Lister tous les utilisateurs
  
  
  • Enregistrer un nouveau compte utilisateur
  
  
• Groupe d'impression
  
  
  
  • ...
  
  

Comme vous pouvez le voir dans l'image ci-jointe, j'ai déjà un groupe - c'est "Groupe d'impression" et "Authentification" et "Documents d'impression" sont des enfants de "Groupe d'impression", donc votre solution ne fonctionne pas pour moi. Avez-vous une autre idée?

Merci

@spark-ftw Ce que @kylef voulait dire est correct. Vous ne pouvez pas avoir de description de démarque aléatoire dans un groupe de ressources ( Group Print ) une fois que vous avez déjà décrit une ressource ( User Collection ).

Vous pouvez faire quelque chose comme ça. (c'est ce que @kylef a proposé).

# 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 : Mise à jour du commentaire après correction d'une petite erreur.

Cela ne m'aide pas, car j'ai besoin de plusieurs sections à l'intérieur de chaque section comme ceci:

• Section d'impression

-- Groupe d'autorisation

--- Collecte utilisateur

--- Authentification de la collecte

-- Groupe de documents

--- Imprimer la collection de documents

--- Enregistrer la collection de documents

• Section d'entraînement

-- Groupe d'autorisation

--- Collecte utilisateur

--- Authentification de la collecte

-- Groupe de documents

--- Imprimer la collection de documents

--- Enregistrer la collection de documents

...

Merci

Des idées?

@spark-ftw J'ai ajouté quelques !comments dans le code ci-dessous. TL;DR Votre rubrique ##L'authentification fait partie de la description du groupe, pas de la description de la ressource. Une fois que vous avez défini le premier point de terminaison d'un groupe, vous venez de terminer la description du groupe et de commencer avec les points de terminaison de ressource.

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, comment puis-je obtenir la structure que je veux ?

@spark-ftw Vous ne pouvez pas avoir le titre que vous voulez si vous insistez sur l'arborescence. Vous pouvez toujours utiliser plusieurs groupes comme :

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

Je suis désolé, mais je ne vois pas d'autre solution que d'utiliser plus de groupes. Mais vous en bénéficierez, car la navigation dans la documentation dans Apiary utilise ces groupes. C'est donc une solution gagnant-gagnant.

Veuillez revoir ma demande :

-Section d'impression

-- Groupe d'autorisation

--- Collecte utilisateur

--- Authentification de la collecte

-- Groupe de documents

--- Imprimer la collection de documents

--- Enregistrer la collection de documents

Section d'entraînement

-- Groupe d'autorisation

--- Collecte utilisateur

--- Authentification de la collecte

-- Groupe de documents

--- Imprimer la collection de documents

--- Enregistrer la collection de documents

À l'exception de l'impression, j'ai également besoin du produit Drive. C'est autre chose (donc j'ai besoin d'un autre niveau de hiérarchie)

Soit dit en passant, la démarque prend en charge cela, seul le rucher a un problème avec son analyse ...

@spark-ftw Ce n'est pas que Apiary a un problème - c'est que la description entre les points de terminaison de ressource n'est pas autorisée à être là - si vous regardez dans les avertissements / problèmes dans Apiary Editor, vous y verrez un avertissement. Selon la spécification https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def -section-structure - une section Group contient ces parties : Nom du groupe , Description du groupe, Ressources du groupe. Rien comme une autre description entre les deux.

Si vous comparez Markdown et API Blueprint, vous vous retrouverez plutôt avec une structure linéaire non arborescente.

@spark-ftw Veuillez noter que le mot-clé Group est utilisé pour indiquer le début du nouveau Section .
API Blueprint ne prend pas du tout en charge l'imbrication de troisième niveau - veuillez consulter le fichier de spécifications lié dans le commentaire ci-dessus.

Donc pas de solution à mon problème ?