사용하지 않는 전역 스키마 정의 (OpenAPI 2.0)

설명

definitions의 스키마는 요청, 응답 또는 다른 모델에서 참조해 사용합니다. 참조되지 않는 스키마는 유효할 수 있지만, 불필요한 모델이 남으면 실제 데이터 계약을 관리하기 어려워집니다.

잠재적 영향

모델 변경의 영향을 파악하기 어려워지고 문서가 불필요하게 복잡해질 수 있습니다.

해결 방법

직접 참조뿐 아니라 다른 스키마와 외부 문서의 사용 여부도 확인하세요. 필요한 모델은 참조하고 더 이상 쓰지 않는 모델만 제거하세요.

예시

다음 POST 예시는 사용하지 않는 Tag를 제거하고 요청 본문에서 참조하는 Category를 유지합니다.

변경 전

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response"
          }
        },
        "parameters": [
          {
            "name": "category",
            "in": "body",
            "description": "max records to return",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Category"
            }
          }
        ]
      }
    }
  },
  "definitions": {
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}

변경 후

json

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