説明
OpenAPI 3.0 の readOnly: true はレスポンスで使用するプロパティを、writeOnly: true はリクエストで使用するプロパティを記述します。同じプロパティで両方を true にすると方向が競合し、仕様に違反します。
想定される影響
- API 利用者が、そのプロパティをリクエストで送るのか、レスポンスで受け取るのか判断しにくくなります。
- コード生成ツールや検証ツールが定義を拒否したり、誤ったリクエスト・レスポンスモデルを作成したりする可能性があります。
対処方法
レスポンス専用のプロパティでは readOnly だけを true に、リクエスト専用では writeOnly だけを true にしてください。両方向で使う場合は両方を省略するか false にしてください。サーバーの入力処理とレスポンスの直列化も、この契約に従っていることを確認してください。
例
オブジェクトスキーマの整数プロパティ id を比較する例です。GeneralError を使うリクエストやレスポンスの定義は省略しています。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0",
"contact": {
"name": "contact",
"url": "https://www.google.com/",
"email": "user@gmail.c"
}
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"writeOnly": true,
"readOnly": true
},
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
},
"required": [
"name"
]
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0",
"contact": {
"name": "contact",
"url": "https://www.google.com/",
"email": "user@gmail.c"
}
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"readOnly": true
},
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
},
"required": [
"name"
]
}
}
}
}
変更後の id は readOnly: true だけを残し、レスポンスで使用するプロパティであることを示しています。スキーマの変更だけで、サーバーの入力処理やアクセス制御が変わるわけではありません。