概要
restfulなapiを設計すっぞ。となっても、「けど同じ戻り値を何回も書きたくない！めんどくさい！」ってなりますよね。
そんなときに、Data Structuresというデータ型定義の方法が使えると知ったのですが、一部ハマったので書き留めておきます。
Data Structuresについては下記を参考にさせてもらいました。感謝！
api blueprint でData Structuresを用いてIFを定義する
https://qiita.com/haseshin/items/1394b0c70e25c9f51762
Data Structuresを利用してみる
Data Structuresを利用しない場合、/hoges のGETはリストで、hoges/{id} のGETはオブジェクトで返すわけですが、オブジェクトの内容は同じになります。
今回はサンプルなので、id とname しかないですが、実際はもっと項目は多いわけで。。。
あとは分かりますよね。。。
# hogeリソース
## hoge情報 [/hoges]
### hoge情報を取得する [GET /hoges]
+ Response 200 (application/json)
+ Attributes
+ items (array, fixed-type)
+ (object)
+ id : 1 (number) - ID
+ name : hoge (string) - 名前
## hoge情報 [/hoges/{id}]
+ Parameters
+ id : 1 (number) - ID
### hoge情報を取得する [GET]
+ Response 200 (application/json)
+ Attributes
+ id : 1 (number) - ID
+ name : hoge (string) - 名前
で、Data Structuresを利用して戻り値をデータ型定義するとスッキリする！
というわけで、先の記事が参考になります。
api blueprint でData Structuresを用いてIFを定義する
https://qiita.com/haseshin/items/1394b0c70e25c9f51762
記事に習って、まずはData Structuresを定義します。
# Data Structures
## Hoge (object)
+ id : 1 (number) - ID
+ age : hoge (string) - 名前
hoges/{id} の戻り値に指定してみます。
## hoge情報 [/hoges/{id}]
+ Parameters
+ id : 1 (number) - ID
### hoge情報を取得する [GET]
+ Response 200 (application/json)
+ Attributes
+ hoge (Hoge)
これで、戻り値はData Structuresを参照することになるので、楽で良いね！
それでは、良きapi blueprintを利用した設計ライフを^^
・
・
・
となれば良かったのですが、実際にjsonの戻り値を見てみます。
{
"hoge": {
"id": 1,
"age": "hoge"
}
}
はい。
おわかりいただけるでしょうか。。。
"hoge": { ... } はいらないんやー。となります。
どうすればよいのか小一時間悩んだ挙げ句、下記のようにすれば良いことがわかりました。
## hoge情報 [/hoges/{id}]
+ Parameters
+ id : 1 (number) - ID
### hoge情報を取得する [GET]
+ Response 200 (application/json)
+ Attributes (Hoge)
結果を見てみます。
{
"id": 1,
"age": "hoge"
}
はい。
期待していた戻り値となりました。
以下がData Structuresを適用したバージョンとなります。
# Data Structures
## Hoge (object)
+ id : 1 (number) - ID
+ age : hoge (string) - 名前
# hogeリソース
## hoge情報 [/hoges]
### hoge情報を取得する [GET /hoges]
+ Response 200 (application/json)
+ Attributes
+ items (array[Hoge], fixed-type)
## hoge情報 [/hoges/{id}]
+ Parameters
+ id : 1 (number) - ID
### hoge情報を取得する [GET]
+ Response 200 (application/json)
+ Attributes (Hoge)
それでは、良きapi blueprintを利用した設計ライフを^^
PS) hogeに複数形はあるのでしょうか・・・知りたい
参考
api blueprint でData Structuresを用いてIFを定義する
https://qiita.com/haseshin/items/1394b0c70e25c9f51762