説明
OpenAPI 3.0のReference Objectでは、$ref以外に追加したプロパティは無視されます。Swagger 2.0の参照も同じJSON Referenceの規則に従います。隣に書いたtypeやdescriptionで参照先を変更できると考えると、意図した契約と実際の定義が異なる場合があります。
この規則をすべての$refの位置や別の仕様バージョンに一律に適用しないでください。例えばPath Itemの$refには別のフィールド規則があります。
想定される影響
意図した制約や説明が適用されず、リクエストやレスポンスの検証、生成されたクライアントが想定と異なる場合があります。
対処方法
これらのバージョンのReference Objectには$refだけを残してください。追加情報は参照先に定義するか、スキーマの位置で制約を併用する必要がある場合はallOfを検討してください。参照先の存在と制約の整合も確認してください。
例
参照の使用箇所だけを示すOpenAPI 3.0の抜粋です。infoと参照先のcomponents.schemas.MyObject定義は別途必要です。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "integer",
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
}
}
変更後は、無視される隣接プロパティtypeを削除します。参照先の型は変わらず、この変更で整数型になるわけではありません。