OpenAPI 링크의 operationId와 operationRef 중복 지정

설명

OpenAPI 3.0 링크에서는 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로 전달하는 관계는 유지하며, 이 선언이 실제 후속 호출을 자동 실행하는 것은 아닙니다.