Apiable: Est-il possible de documenter ce que sont les champs de réponse JSON?

Question

Je voudrais documenter ce que les champs JSON sont eux-mêmes représentés.

J'ai documenté la déclaration GET et les paramètres, mais cela ne fait pas une documentation complète à donner aux utilisateurs.

Donc, dans l'exemple ci-dessous, comment puis-je ajouter un commentaire sur "AutresFields".Est-ce pris en charge?Ou dois-je faire un document compagnon quelque part ailleurs?

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

Mise à jour: nous venons de déployer une version bêta d'attributs en utilisant le syntaxe MSON .

La charge utile d'origine pourrait être ensuite décrite comme

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

Remarque Le JSON explicite dans le corps est redondant et vous pouvez le sauter complètement.Voir API Blueprint Spécification - Attributs pour plus de détails

Answer 2

Je ne pense pas que cela soit pris en charge.

J'ai résolu ce problème dans mon projet en mettant une table avec la description juste au-dessus de la ligne de demande d'obtention.Dans votre cas, on pourrait ressembler à:

### List all Applications 

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

### Get List of Applications [GET]

Pour vous aider à créer la table de la syntaxe de Markdown, vous pouvez utiliser Générateur de tables de marque .

Notez que le générateur de table vous permet de sauvegarder la définition de la table dans un fichier alors vous aurez besoin de modifier la table que vous pouvez commencer à partir de l'endroit où vous vous êtes laissé.