Imkerei: Ist es möglich zu dokumentieren, welche JSON-Antwortfelder sind?

Question

Ich möchte dokumentieren, was die eigentlichen JSON-Felder selbst darstellen.

Ich habe die GET-Anweisung und die Parameter dokumentiert, aber das macht den Benutzern keine vollständige Dokumentation.

Also, in dem Beispiel unten, wie würde ich einen Kommentar über "OtherFields" hinzufügen. Wird das unterstützt? Oder muss ich ein Begleitdokument woanders machen.

## View Applications [/cat{?sort}{&order}{&page}] 
### List all Applications 
### Get List of Applications [GET] 
+ Parameters 
    + sort (optional, string) ... `sort` parameter is used to specify which criteria to use for sorting. One of the following strings may be used: 
    `"NAME", 
    "RATING", "QUALITY" , 
    "RISKLEVEL", ` 

    + order (optional, string) ... `order` parameter is used to specify which order to use if sorting is used. One of the following strings may be used: 
    `"ASC", 
    "DESC"` 

    + page (optional, int) ... `page` parameter is used to request subsequent catalog pages. 


+ Response 200 (application/json) 

       { 
      "Catalog" : { 
       "Page" : 0, 
       "Count" : 6, 
       "Applications" : [{ 
         "UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad" 
         "OtherFields: "" 
       }] 
       }} 

Answer 1

Update: Wir haben gerade eine Beta der Attribute Beschreibung mit der MSON syntax ausgerollt.

Die ursprüngliche Nutzlast dann als

### Get List of Applications [GET] 

+ Response 200 (application/json) 

    + Attributes 
     + Catalog (object) 
      + Page: 0 (number) - Number of the page 
      + Count: 6 (number) - Count of *Lorem Ipsum* 
      + Applications (array) - Some array of something 
       + (object) 
        + UID: `6882e96a-5da1-11e3-1111-3f24f45df3ad` 
        + OtherFields 

    + Body 

      { 
       "Catalog" : { 
        "Page" : 0, 
        "Count" : 6, 
        "Applications" : [{ 
         "UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad" 
         "OtherFields": "" 
        }] 
       } 
      } 

Notiere die explizite JSON in Körper beschrieben werden könnte überflüssig ist und Sie können es ganz überspringen. Weitere Details finden Sie in der API Blueprint-Spezifikation - .

Answer 2

Ich glaube nicht, dass es noch unterstützt wird.

Ich löste dieses Problem in meinem Projekt, indem ich eine Tabelle mit der Beschreibung direkt über der GET-Anforderungszeile legte. In Ihrem Fall könnte es wie folgt aussehen:

### List all Applications 

| Field       | Description    | 
|----------------------------------|---------------------------| 
| Catalog.Applications.OtherFields | Documentation goes here.. | 

### Get List of Applications [GET] 

Damit Sie die Tabelle in Markdown-Syntax erstellen Sie Markdown Tables generator verwenden können.

Beachten Sie, dass Sie mit dem Tabellengenerator die Tabellendefinition in einer Datei speichern können, damit Sie die nächste Tabelle bearbeiten können, wo Sie an der Stelle beginnen können, an der Sie aufgehört haben.