Apiary: Можно ли документировать, какие поля ответа JSON есть?

Question

Я хотел бы документировать, что представляют собой собственно поля JSON.

Я документировал инструкцию GET и параметры, но это не дает полную документацию для пользователей.

Итак, в приведенном ниже примере, как добавить комментарий к «OtherFields». Поддерживается ли это? Или мне нужно сделать компаньонный документ где-то в другом месте.

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

Обновление: Мы только что развернули бета описание атрибутов, используя MSON syntax.

оригинальная полезная нагрузка может быть затем описан как

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

Примечания явного JSON в теле является излишним, и вы можете пропустить его полностью. См. Спецификацию API Blueprint - Attributes для получения дополнительной информации

Answer 2

Я не думаю, что он поддерживается.

Я решил эту проблему в своем проекте, поставив таблицу с описанием прямо над строкой запроса GET. В вашем случае это может выглядеть следующим образом:

### List all Applications 

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

### Get List of Applications [GET] 

Чтобы создать таблицу в синтаксисе Markdown вы можете использовать Markdown Tables generator.

Обратите внимание, что генератор таблицы позволяет сохранить определение таблицы в файл, чтобы в следующий раз вам нужно было отредактировать таблицу, с которой вы можете начать, с того места, где вы остановились.