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を使用して属性の説明のベータ版を公開しました。

元のペイロードは、次に、身体中の明示的なJSONは冗長であり、あなたはそれを完全に省略でき

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

注記として記載することができます。 APIブループリント仕様 - Attributesを参照してください。

Answer 2

まだサポートされていないと思います。

私のプロジェクトでは、GET要求行のすぐ上に説明があるテーブルを置くことでこの問題を解決しました。あなたはMarkdown Tables generatorを使用することができますマークダウン構文でテーブルを作成するための

### List all Applications 

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

### Get List of Applications [GET] 

：あなたのケースでは、それは次のようになります。

テーブルジェネレータを使用すると、テーブル定義をファイルに保存できるため、次に編集したテーブルを編集する必要があります。