25
13

More than 5 years have passed since last update.

API Blueprint(aglio)で、生成されたSchemaのarrayにitemsがない

Posted at

tl;dr

arrayにしたプロパティにfixed-typeオプションをつける。

- + books: (array[Book])
+ + books: (array[Book], fixed-type) 

公式にしっかり書いてありますね。無駄にGithubとか調べてしまった。。

何が起きたの?

API BlueprintでAPIドキュメントを作成していたときに、どうにもarrayの中身がドキュメント化されない事が気持ち悪くなったので調べてみた。

例えば。次のドキュメントだとこのように変換される。

input.apib
+ Response 200 (application/json)
    + Attributes
        + books (array[object])
            + (object)
                + name: ほんのなまえ (string, required) - 書籍名
                + cost: 50 (number, required) - 価格
Body
{
  "books": [
    {
      "name": "ほんのなまえ",
      "cost": 50
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "books": {
      "type": "array"
    }
  }
}

Bodyはまぁ良いが、Schemaはあまり意味をなさなくなってしまう(折角input.apibで定義した意味が・・・)ので、ここにitemsプロパティをどうにか入れられないかという話。

答えは前にも書いたとおり、arrayにしたプロパティにfixed-typeをつける。

input.apib
 + Response 200 (application/json)
     + Attributes
-        + books (array[object])
+        + books (array[object], fixed-type)
             + (object)
                 + name: ほんのなまえ (string, required) - 書籍名
                 + cost: 50 (number, required) - 価格
Body
{
  "books": [
    {
      "name": "ほんのなまえ",
      "cost": 50
    }
  ]
}
Schema
{
  "$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を見てから、公式資料に載っているのを見つけました。
それにしても、なんでデフォルトではないんでしょうか。皆さんそんなに気にならないのかな。。

25
13
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
25
13