OpenAPI 3.0 빈 배열의 의미 점검

설명

OpenAPI 3.0에서 빈 배열의 의미는 필드마다 다릅니다. enum: []에는 허용 값이 없지만, 작업의 security: []는 전역 보안 요구사항을 제거하는 유효한 선언입니다. 빈 배열이라는 이유만으로 임의의 값을 넣어서는 안 됩니다.

잠재적 영향

값이 필요한 배열을 비워 두면 검증이나 클라이언트 생성에 문제가 생길 수 있습니다.
의도적인 빈 값과 누락을 혼동하면 문서의 인증 요구사항이나 데이터 계약을 잘못 바꿀 수 있습니다.

해결 방법

필드의 용도와 OpenAPI 3.0에서의 의미를 확인하세요. 값이 필요한 배열에는 실제 동작을 반영한 항목을 추가하고, 의도적인 빈 배열은 유지하세요. 인증 선언을 바꿀 때는 실제 접근 정책과 서버의 인증 처리도 확인하세요.

예시

첫 예제는 상태 응답의 enum에 허용 값을 지정하지 않았습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {"title": "Status API", "version": "1.0.0"},
  "paths": {
    "/status": {
      "get": {
        "responses": {
          "200": {
            "description": "Current status",
            "content": {
              "application/json": {
                "schema": {"type": "string", "enum": []}
              }
            }
          }
        }
      }
    }
  }
}

변경 후