説明
itemsは配列の要素を記述します。オブジェクトや文字列のスキーマに追加しても、オブジェクトの項目や文字列の内容を制限するものではありません。実際の型に合わないキーワードは、API契約の誤解につながる場合があります。
想定される影響
利用者が意図した検証は適用されると思い込んだり、実際のデータと異なる型のコードを生成したりする場合があります。
対処方法
実際のデータが配列ならtype: arrayと要素を表すitemsを定義してください。オブジェクトならpropertiesなどの制約を使い、無関係なitemsを削除してください。キーワードに合わせるためにAPIの実際のデータ型を勝手に変更しないでください。
例
infoとpathsを省略したOpenAPI 3.0のスキーマ例です。実際の契約が文字列配列の場合を比較します。
変更前
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"items": {
"type": "string"
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
変更前のitemsはオブジェクトの項目を文字列に制限しません。変更後は文字列配列を宣言します。実際のデータがオブジェクトなら、型を変えずにその項目を正しく定義してください。