OpenAPI 3.0 객체의 필수 속성 누락

설명

OpenAPI 3.0의 각 객체에는 필수 속성이 있습니다. 예를 들어 info에는 title과 version이 필요하고, Response 객체에는 description이 필요합니다. 필수 속성이 빠지면 명세가 불완전해져 문서 표시나 도구 처리에 문제가 생길 수 있습니다.

잠재적 영향

• API의 식별 정보나 요청·응답 설명이 누락될 수 있습니다.
• 명세 검증이 실패하거나 문서·클라이언트 생성에 문제가 생길 수 있습니다.

해결 방법

문서가 사용하는 OpenAPI 버전과 객체 종류에 따라 필수 속성을 확인하고 실제 내용을 채우세요. 최상위 openapi, info, paths뿐 아니라 중첩 객체도 검토하세요. 수정 후 전체 명세를 검증하세요.

예시

다음은 info.title의 누락을 수정하는 예시입니다. paths가 빈 객체인 것은 허용되며, 이 예제에는 API 작업을 넣지 않았습니다.

변경 전

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "/",
      "email": "user@gmail.com"
    }
  },
  "paths": {}
}

변경 후

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "/",
      "email": "user@gmail.com"
    }
  },
  "paths": {}
}

변경 후에는 title과 version이 모두 있어 API의 기본 식별 정보를 제공합니다. 실제 문서에서는 다른 객체의 필수 속성도 함께 확인해야 합니다.

참조

• CWE-665
• OpenAPI Specification
• OpenAPI 3.0.3 명세