사용하지 않는 전역 응답 정의 (OpenAPI 2.0)

설명

전역 responses에 정의한 응답은 작업에서 참조해 재사용합니다. 사용하지 않는 응답이 남아 있어도 명세가 곧바로 잘못되는 것은 아니지만, 실제 응답 계약을 파악하기 어려워질 수 있습니다.

잠재적 영향

어떤 응답을 실제로 반환하는지 혼동하고 불필요한 정의까지 유지보수할 수 있습니다.

해결 방법

사용하는 응답은 작업의 상태 코드에 맞춰 참조하세요. 다른 문서의 사용 여부를 포함해 확인하고, 필요 없는 공통 응답만 제거하세요.

예시

다음 POST 예시는 사용하지 않는 IllegalInput과 GeneralError를 제거하고 참조 중인 Success를 유지합니다.

변경 전

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/responses/Success"
          }
        },
        "parameters": [
          {
            "name": "limit2",
            "in": "body",
            "description": "max records to return",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "responses": {
    "Success": {
      "description": "200 response"
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error"
    }
  }
}

변경 후

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/responses/Success"
          }
        },
        "parameters": [
          {
            "name": "limit2",
            "in": "body",
            "description": "max records to return",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "responses": {
    "Success": {
      "description": "200 response"
    }
  }
}