OpenAPI 경로의 작업 공개 범위 점검

설명

경로 항목에 작업이 없으면 그 경로가 지원하는 요청을 문서에서 확인할 수 없습니다. 다만 OpenAPI 3.0과 2.0은 접근 제어에 따라 빈 경로 항목을 허용하며, $ref로 참조한 경로 항목에 작업이 정의되어 있을 수도 있습니다.

잠재적 영향

공개해야 할 작업이 누락되면 API 소비자가 지원하는 메서드를 알 수 없고 문서 기반 연동이나 테스트가 불완전해질 수 있습니다. 문서에서 작업을 숨기는 것만으로 서버 접근이 차단되지는 않습니다.

해결 방법

문서 대상 사용자에게 제공할 작업과 참조한 경로 항목을 확인하세요. 실제로 제공하면서 문서에 공개해야 하는 HTTP 메서드와 응답만 추가하고, 의도적인 빈 항목을 불필요하게 채우지 마세요. 서버의 인증과 권한 제어는 별도로 적용하세요.

예시

OpenAPI 3.0에서 빈 경로 항목과 작업이 있는 항목을 비교합니다. info는 생략했습니다. 빈 항목 자체가 명세 위반은 아닙니다.

변경 전

{
  "openapi": "3.0.0",
  "paths": {
    "/": {}
  }
}

변경 후

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

변경 후에는 GET /와 200 응답을 설명합니다. 이 작업을 실제로 제공하고 해당 사용자에게 문서화해야 할 때 적절한 추가입니다.

참조

• OpenAPI Specification - Path Item Object
• CWE-710: Improper Adherence to Coding Standards
• OpenAPI 3.0.3 경로 항목
• OpenAPI 2.0 경로 항목