사용되지 않는 OpenAPI 3.0 콜백 컴포넌트

설명

components.callbacks에 정의한 콜백이 작업에서 참조되지 않으면 해당 작업의 콜백 계약에 연결되지 않습니다. 사용 중인 콜백은 작업의 callbacks에서 참조하고, 다른 문서에서도 사용하지 않는 불필요한 정의는 정리하세요.

잠재적 영향

사용되지 않는 콜백을 실제 API 기능으로 오해할 수 있습니다.
API 변경 시 불필요한 정의까지 검토해야 하므로 문서 유지보수가 어려워집니다.

해결 방법

콜백이 필요한 작업의 callbacks에서 컴포넌트를 $ref로 참조하세요. 삭제 전 다른 문서나 도구의 참조도 확인하고, 수정 후 참조 대상과 콜백 URL 표현식이 올바른지 검증하세요.

예시

다음은 콜백 정의와 작업 연결을 비교합니다. POST 요청 본문에서 inProgressUrl을 제공하는 부분은 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  },
  "components": {
    "callbacks": {
      "inProgress": {
        "{$request.body#/inProgressUrl}": {
          "post": {
            "requestBody": {
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object"
                  }
                }
              }
            },
            "responses": {
              "200": {
                "description": "OK"
              }
            }
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "Success"
          }
        },
        "callbacks": {
          "myEvent": {
            "$ref": "#/components/callbacks/inProgress"
          }
        }
      }
    }
  },
  "components": {
    "callbacks": {
      "inProgress": {
        "{$request.body#/inProgressUrl}": {
          "post": {
            "requestBody": {
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object"
                  }
                }
              }
            },
            "responses": {
              "200": {
                "description": "OK"
              }
            }
          }
        }
      }
    }
  }
}

변경 후에는 callbacks.myEvent가 inProgress를 참조합니다. 이 선언은 콜백 계약을 문서화하며, 서버의 실제 후속 요청을 구현하지는 않습니다.