Api-blueprint: Mehrere Abschnitte innerhalb einer Gruppe festlegen

@spark-ftw Leider ist die erste Überschrift Authentication nur an die Beschreibung der Ressourcengruppe Print angehängt. Die Beschreibung wird direkt unter der Ressourcenüberschrift angezeigt und dann werden alle Ressourcen unten aufgelistet.

Ich würde vorschlagen, dies leicht umzugestalten, um verschiedene Ressourcengruppen wie folgt zu gruppieren:

• Authentifizierungsgruppe
  
  
  
  • Sammlung von Benutzerressourcen
  
  
  • Alle Benutzer auflisten
  
  
  • Neues Benutzerkonto registrieren
  
  
• Gruppe drucken
  
  
  
  • ...
  
  

Wie Sie im angehängten Bild sehen können, habe ich bereits eine Gruppe - es ist "Druckgruppe" und die "Authentifizierung" und "Dokumente drucken" sind Kinder von "Gruppe drucken", sodass Ihre Lösung für mich nicht funktioniert. Hast du eine andere Idee?

Vielen Dank

@spark-ftw Was @kylef meinte, ist richtig. Sie können keine zufällige Markdown-Beschreibung innerhalb einer Ressourcengruppe ( Group Print ) haben, wenn Sie bereits eine Ressource beschrieben haben ( User Collection ).

Sie können so etwas tun. (was @kylef vorgeschlagen hat).

# 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

            {}

BEARBEITEN : Der Kommentar wurde aktualisiert, nachdem ein kleiner Fehler behoben wurde.

Dies hilft mir nicht, da ich mehrere Abschnitte in jedem Abschnitt benötige:

• Abschnitt drucken

-- Auth-Gruppe

--- Benutzersammlung

--- Auth-Sammlung

-- Docs-Gruppe

--- Dokumentensammlung drucken

--- Dokumentensammlung speichern

• Antriebsbereich

-- Auth-Gruppe

--- Benutzersammlung

--- Auth-Sammlung

-- Docs-Gruppe

--- Dokumentensammlung drucken

--- Dokumentensammlung speichern

...

Vielen Dank

Irgendwelche Ideen?

@spark-ftw Ich habe dem Code unten einige !comments hinzugefügt. TL;DR Ihre Überschrift ##Authentifizierung ist Teil der Gruppenbeschreibung, nicht Teil der Ressourcenbeschreibung. Nachdem Sie den ersten Endpunkt in einer Gruppe definiert haben, haben Sie gerade die Gruppenbeschreibung beendet und mit Ressourcenendpunkten begonnen.

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, wie kann ich die gewünschte Struktur erreichen?

@spark-ftw Sie können nicht die gewünschte Überschrift haben, wenn Sie auf der Baumstruktur bestehen. Sie können weiterhin mehrere Gruppen verwenden als:

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

Es tut mir leid, aber ich sehe keine andere Lösung, um mehr Gruppen zu verwenden. Aber Sie werden davon profitieren - denn die Navigation in der Dokumentation in Apiary verwendet diese Gruppen. Es ist also eine Win-Win-Lösung.

Bitte sehen Sie sich noch einmal meine Anfrage an:

-Druckbereich

-- Auth-Gruppe

--- Benutzersammlung

--- Auth-Sammlung

-- Docs-Gruppe

--- Dokumentensammlung drucken

--- Dokumentensammlung speichern

Antriebsbereich

-- Auth-Gruppe

--- Benutzersammlung

--- Auth-Sammlung

-- Docs-Gruppe

--- Dokumentensammlung drucken

--- Dokumentensammlung speichern

Außer Print benötige ich auch Drive-Produkte. Das ist etwas anderes (also brauche ich eine andere Hierarchieebene)

Übrigens, der Markdown unterstützt dies, nur Imkerei hat ein Problem mit dem Parsen...

@spark-ftw Es ist nicht so, dass Apiary ein Problem hat - es ist so, dass die Beschreibung zwischen Ressourcenendpunkten nicht vorhanden sein darf - wenn Sie sich die Warnungen / Probleme im Apiary-Editor ansehen, sehen Sie dort eine Warnung. Gemäß der Spezifikation https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def -section-structure - enthält eine Group Sektion diese Teile: Gruppenname , Gruppenbeschreibung, Gruppenressourcen. Nichts als eine andere Beschreibung dazwischen.

Wenn Sie Markdown vs. API Blueprint vergleichen, werden Sie stattdessen mit einer linearen Nicht-Baumstruktur enden.

@spark-ftw Bitte beachten Sie, dass das Schlüsselwort Group verwendet wird, um den Beginn eines neuen Section .
API Blueprint unterstützt überhaupt keine Verschachtelung auf dritter Ebene - siehe die Spezifikationsdatei, die oben im Kommentar verlinkt ist.

Also keine Lösung für mein Problem?