説明
OpenAPI 3.0のサーバーURLで使う変数は、同じServer Objectのvariablesに定義する必要があります。各変数には、別の値が指定されない場合に使う文字列のdefaultが必要です。
想定される影響
置換する値が定義されていないと、ドキュメントツールやクライアントが意図したサーバーアドレスを生成できない場合があります。
対処方法
URLの各プレースホルダーと同じ名前で変数を定義し、適切な文字列のデフォルト値を指定してください。選択肢を制限する場合はenumを検討し、デフォルト値と選択した値から完成するURLを確認してください。
例
サーバーURLの変数に絞ったLinkの抜粋です。対象操作を指定するoperationIdまたはoperationRefも必要ですが、ここでは省略しています。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"summary": "List API versions",
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"links": {
"address": {
"server": {
"url": "https://development.{server}.com/{base}"
}
}
}
}
},
"operationId": "listVersionsv2"
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"summary": "List API versions",
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"links": {
"address": {
"server": {
"url": "https://development.{server}.com/{base}",
"variables": {
"base": {
"default": "v2"
},
"server": {
"default": "gigant-server"
}
}
}
}
}
}
},
"operationId": "listVersionsv2"
}
}
}
}
変更前にはserverとbaseの置換値がありません。追加したデフォルト値を使うと、https://development.gigant-server.com/v2になります。