Mix Request/Response Body und Datenstrukturen

Question

Ich möchte mit aglio/api Blueprint eine nette Dokumentation für unsere neue API erstellen.

Der JSON könnte ziemlich groß sein (mit vielen optionalen Werten), also würde ich gerne einen korrekten Anwendungsfall im Rumpf angeben, aber auch Datenstrukturen für das JSON-Schema verwenden. Immer wenn das Schema jedoch genau zum Körper passt, wirft das resultierende HTML "Hallo, Welt!" An mich, da ich die Beispieldaten nicht ausgefüllt habe - aber da ich ein vollständiges und gültiges Beispiel im Körper habe Ich hätte nicht erwartet, dass Aglio Hello World produziert.

Als Referenz ist das, was ich in dem resultierenden htmls Körper erscheinen erwarten:

{ 
    "a": "i want this to appear", 
    "b": "in my aglio", 
    "c": "html file" 
} 

Dies ist, was erscheint tatsächlich tut:

{ 
    "a": "Hello, world!", 
    "b": "Hello, world!", 
    "c": "Hello, world!", 
    "d": "Hello, world!" 
} 

Und das ist der rohe api Bauplan:

FORMAT: 1A 

# JSON Schema 

# Test [/post/something] 

## A Test [POST] 

+ Request (application/json) 
    + Attributes (SomeObject) 

    + Body 

     { 
      "a": "i want this to appear", 
      "b": "in my aglio", 
      "c": "html file" 
     } 

+ Response 200 

# Data Structures 
## SomeObject (object) 
+ a (string) - A 
+ b (string) - B 
+ c (string) - C 
+ d (string, optional) - I'm optional, yet don't want to appear in the html, only the schema 

Also, zuerst: Ist das ein gültiger Weg, Dinge zu tun? Würden Sie einen anderen Ansatz empfehlen? Ist das ein Fehler in Aglio, weil es im Bienenhaus so funktioniert, wie ich es vorhabe? Danke!

Answer 1

Das entsprechende GitHub-Problem gefunden, sieht aus wie nichts mit meiner Beschreibung falsch ist. https://github.com/danielgtaylor/aglio/issues/221

Answer 2

Sie können folgende Aktionen

FORMAT: 1A 
# JSON Schema 
# Test [/post/something] 
JSON Schema Title 
## A Test [POST] 

+ Request (application/json) 
    + Attributes (object) 
     + a a-value (string, required) - description about a 
     + b b-value (number, required) - description about b 
     + c c-value (string, required) - description about c 
     + d [a1, a2, a3] (array, optional) - I'm optional 

+ Response 200 (application/json) 
    { 
    "message": "this works" 
    } 

einen a-Wert (Zeichenfolge, erforderlich) - Beschreibung In über die Linie "a" -> Attributnamen, "a-Wert" -> erscheint im body, "(string, required)" -> für Schema-Generierung, "description" -> schema attribute description