説明
OpenAPI 3.0とSwagger 2.0では、スキーマをarray型として宣言した場合、itemsで要素を定義する必要があります。定義がないと文書検証やコード生成に失敗したり、配列の内容を一貫して解釈できなかったりする場合があります。
想定される影響
要素の型が不明確になり、利用者がリクエストやレスポンスの形式を誤解して連携に失敗する可能性があります。
対処方法
itemsに要素の型または参照スキーマを指定してください。OpenAPI 3.0のパラメーターではスキーマ内に、Swagger 2.0の本文以外の配列パラメーターではパラメーター自体にitemsを設定してください。
例
OpenAPI 3.0のスキーマの抜粋です。完全な文書に必要なinfoとpathsは省略しています。
変更前
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "array"
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
変更前には要素の定義がありません。変更後はitems.type: stringで文字列の配列を示します。実際のリクエストとレスポンスもこの契約に合うか確認してください。