Apiaia: è possibile documentare i campi di risposta JSON?

Question

Vorrei documentare ciò che rappresentano gli stessi campi JSON reali.

Ho documentato l'istruzione GUETA e i parametri, ma questo non effettua una documentazione completa da dare agli utenti.

Quindi, nell'esempio seguente come aggiungerei un commento su "altri campi".Questo è supportato?O devo fare un documento da compagnia da qualche altra parte.

## 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

Aggiornamento: abbiamo appena rotolato una beta di attributi Descrizione usando il MSON Syntax .

Il carico utile originale potrebbe essere quindi descritto come

### 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": ""
                    }]
                }
            }

.

Nota L'esplicito JSON nel corpo è ridondante e puoi saltarlo completamente.Vedi le specifiche del blueprint API - Attributi per ulteriori dettagli

Answer 2

Non penso che sia ancora supportato.

Ho risolto questo problema nel mio progetto mettendo un tavolo con la descrizione proprio sopra la linea di richiesta Ottieni.Nel tuo caso potrebbe sembrare come:

### List all Applications 

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

### Get List of Applications [GET]

.

Per aiutarti a creare la tabella nella sintassi di markdown è possibile utilizzare Markdown Tables Generator .

Nota che il generatore della tabella consente di salvare la definizione della tabella in un file in modo successivo alla prossima volta che è necessario modificare la tabella è possibile iniziare da dove si è interrotta.