説明
レスポンス本文の構造が定義されていないと、クライアントは返されたデータの処理方法を判断しにくくなります。本文がないレスポンスに本文のスキーマは不要です。本文の有無は実際のAPI仕様に基づいて判断してください。
想定される影響
クライアントで解析エラーが起きたり、SDKモデルが誤ったものになったりする可能性があります。応答構造の変更による互換性の問題も検出しにくくなります。
対処方法
OpenAPI 3.0で本文構造を指定する場合は、レスポンスのcontent内にメディアタイプとschemaを定義してください。OpenAPI 2.0では、レスポンスのschemaと適用されるproducesを使用します。実際の戻り値と一致するように保ってください。
例
この例では、OpenAPI 3.0のJSONレスポンスを共通のApiVersionスキーマで記述しています。参照先の定義は、この抜粋では省略しています。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiVersion"
}
}
}
}
}
}
}
}
}