api blueprint でData Structuresを用いてIFを定義する

#aglioを用いたhtmlの生成
api blueprintで記述したAPI定義をaglioというレンダラーを用いて静的なHTMLとして出力することができます。その際にData Structuresというデータ型定義の方法があるのでポイントがあるのでまとめてみます。

##Data Structuresを用いたデータ型の定義
APIごとに戻りの形を記述するのではなく、共通の形はDetaStructuresを用いてスキーマ定義することが可能です。XMLにおけるxsdですね。
インターフェース定義と同一のファイルに定義しても良いですし、別ファイルに定義してもOKです。別ファイルに定義した場合のマージ方法はこちらを参照してください。型を外出しにして定義しておくことでデータ型が変更になった際にはここだけ修正すれば良い事になります。

datastructure.apib

# Data Structures

## Person(object)
+ name: haseshin (string,required) - 名前
+ age:18  (string,required) - 年齢

##DataStructuresを用いた場合のIF定義
DataStructuresをもちいた場合にAPIの戻りの形を指定するには以下のように行います。

interface.apib

+ Response 200 (application/json)
    + Attributes
      + person(Person)

##arrayを使う場合の注意点
配列の場合には以下のように定義します。

interface.apib

+ Response 200 (application/json)
    + Attributes
      + persons(array[Person])

このままaglioで出力した場合、DataStructures側で定義した戻りのSchema情報に説明が含まれません。
この定義だとオブジェクトの配列であることを示していることに過ぎず、Personはそのサンプル･データという扱いになるためと思われます。

戻りのSchemaに説明を含めるには以下のように、Person型の配列であるということを明示的に定義します。

interface.apib

+ Response 200 (application/json)
    + Attributes
      + persons(array[Person],fixed-type)

##まとめ
Data Structuresに型定義をすることで、APIを効率的に定義することが可能になります。
また、配列で固定の型を戻す際にはfixed-typeを使用することでschemaにプロパティの説明を含めることが可能になります。