tl;dr
array
にしたプロパティにfixed-type
オプションをつける。
- + books: (array[Book])
+ + books: (array[Book], fixed-type)
公式にしっかり書いてありますね。無駄にGithubとか調べてしまった。。
何が起きたの?
API BlueprintでAPIドキュメントを作成していたときに、どうにもarray
の中身がドキュメント化されない事が気持ち悪くなったので調べてみた。
例えば。次のドキュメントだとこのように変換される。
+ Response 200 (application/json)
+ Attributes
+ books (array[object])
+ (object)
+ name: ほんのなまえ (string, required) - 書籍名
+ cost: 50 (number, required) - 価格
{
"books": [
{
"name": "ほんのなまえ",
"cost": 50
}
]
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"books": {
"type": "array"
}
}
}
Bodyはまぁ良いが、Schemaはあまり意味をなさなくなってしまう(折角input.apib
で定義した意味が・・・)ので、ここにitemsプロパティをどうにか入れられないかという話。
答えは前にも書いたとおり、array
にしたプロパティにfixed-type
をつける。
+ Response 200 (application/json)
+ Attributes
- + books (array[object])
+ + books (array[object], fixed-type)
+ (object)
+ name: ほんのなまえ (string, required) - 書籍名
+ cost: 50 (number, required) - 価格
{
"books": [
{
"name": "ほんのなまえ",
"cost": 50
}
]
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"books": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "書籍名"
},
"cost": {
"type": "number",
"description": "価格"
}
},
"required": [
"name",
"cost"
]
}
}
}
}
ちゃんと出力されるようになりました。
参考URL
4.3 Nested Member Type - MSON Specification | API Blueprint
Arrays in JSONSchema do not contain `items` field · Issue #243 · danielgtaylor/aglio - Github
Githubのissuesを見てから、公式資料に載っているのを見つけました。
それにしても、なんでデフォルトではないんでしょうか。皆さんそんなに気にならないのかな。。