잘못된 링크 객체 참조 (OpenAPI 3.0)

설명

응답의 링크 참조는 유효한 링크 객체를 가리켜야 합니다. 경로나 대상이 잘못되면 응답 이후 호출할 작업과 전달할 값의 연결 정보를 불러올 수 없습니다.

잠재적 영향

문서에서 후속 호출 정보가 누락되거나 참조 해석이 실패할 수 있습니다.

해결 방법

공통 링크는 #/components/links/...의 실제 정의를 참조하세요. 유효한 외부 링크 객체도 사용할 수 있습니다. 링크가 지정하는 작업과 매개변수도 확인하세요.

예시

다음 발췌 예시는 address 링크의 참조 경로를 수정합니다. 외부 모델, 오류 모델, 후속 작업의 정의는 생략했습니다.

변경 전

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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "$ref": "../models/pet.yaml"
      },
      "User": {
        "$ref": "https://api.example.com/v2/openapi.yaml#/components/schemas/User"
      }
    },
    "responses": {
      "NotFound": {
        "description": "The specified resource was not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "links": {
          "l": {
            "$ref": "#components/linfks/address"
          }
        }
      }
    },
    "links": {
      "address": {
        "operationId": "getUssssserAddress",
        "parameters": {
          "userId": "$request.path.id"
        }
      }
    }
  }
}

변경 후

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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "$ref": "../models/pet.yaml"
      },
      "User": {
        "$ref": "https://api.example.com/v2/openapi.yaml#/components/schemas/User"
      }
    },
    "responses": {
      "NotFound": {
        "description": "The specified resource was not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "links": {
          "l": {
            "$ref": "#/components/links/address"
          }
        }
      }
    },
    "links": {
      "address": {
        "operationId": "getUssssserAddress",
        "parameters": {
          "userId": "$request.path.id"
        }
      }
    }
  }
}