説明
OpenAPI 3.0 の Link オブジェクトでは、operationId と operationRef を同時に指定できません。同じ操作を指していても、相互排他的なフィールドなので一方だけを使用する必要があります。
想定される影響
- 仕様書の検証が失敗したり、ツールによってリンクの扱いが異なったりする場合があります。
- API 利用者がリンク先の操作を判断しにくくなる可能性があります。
対処方法
文書内の一意の操作 ID で接続する場合は operationId、操作を指す URI で接続する場合は operationRef を使ってください。他方のフィールドを削除し、参照先と渡すパラメーターが正しいか検証してください。
例
最初の例は同じ操作を operationId と operationRef の両方で指定しています。この再利用可能な応答を実際の操作に接続する部分と外部スキーマ文書は省略しています。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
}
}
}
}
},
"/users/{userid}/address": {
"parameters": [
{
"name": "userid",
"in": "path",
"required": true,
"description": "the user identifier, as userId",
"schema": {
"type": "string"
}
}
],
"get": {
"operationId": "getUserAddress",
"responses": {
"200": {
"description": "the user's address"
}
}
}
}
},
"components": {
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"links": {
"address": {
"operationId": "getUserAddress",
"operationRef": "#/paths/~1users~1{userid}~1address/get",
"parameters": {
"userid": "$response.body#/uuid"
}
}
}
}
},
"schemas": {
"Pet": {
"$ref": "../models/pet.yaml"
},
"User": {
"$ref": "https://api.example.com/v2/openapi.yaml#/components/schemas/User"
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
}
}
}
}
},
"/users/{userid}/address": {
"parameters": [
{
"name": "userid",
"in": "path",
"required": true,
"description": "the user identifier, as userId",
"schema": {
"type": "string"
}
}
],
"get": {
"operationId": "getUserAddress",
"responses": {
"200": {
"description": "the user's address"
}
}
}
}
},
"components": {
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"links": {
"address": {
"operationId": "getUserAddress",
"parameters": {
"userid": "$response.body#/uuid"
}
}
}
}
},
"schemas": {
"Pet": {
"$ref": "../models/pet.yaml"
},
"User": {
"$ref": "https://api.example.com/v2/openapi.yaml#/components/schemas/User"
}
}
}
}
変更後は operationId だけを残しています。応答の uuid を対象の userid に渡す関係は維持されますが、この宣言が後続の呼び出しを自動実行するわけではありません。