잘못된 HTTP 응답 상태 코드

설명

OpenAPI 응답 키에는 유효한 HTTP 상태 코드나 default를 사용합니다. 1xx 정보성 응답도 유효합니다. OpenAPI 3.0에서는 1XX부터 5XX까지의 대문자 범위 표현도 허용하지만, OpenAPI 2.0은 이 범위 표현을 정의하지 않습니다.

응답 키는 클라이언트와 API 도구가 각 상태의 의미를 이해하는 데 사용합니다. 문서의 상태 코드와 응답 설명은 실제 API 동작에 맞아야 합니다.

잠재적 영향

• API 문서가 구현의 응답 상태를 정확히 설명하지 못할 수 있습니다.
• 코드 생성기, 문서 도구, 테스트 도구가 잘못된 응답 키를 거부하거나 서로 다르게 처리할 수 있습니다.
• 문서와 실제 응답이 다르면 클라이언트의 오류 처리나 리다이렉션 처리가 의도대로 동작하지 않을 수 있습니다.

해결 방법

구현이 실제 반환하는 상태에 맞는 코드를 사용하세요. 일반적인 예는 200, 404, 500이며, 개별적으로 정의하지 않은 응답은 default로 설명할 수 있습니다. 범위 표현이 필요하면 OpenAPI 3.0의 대문자 형식을 사용하고, 2.0에서는 개별 상태 코드나 default를 사용하세요. 각 코드의 의미는 HTTP 상태 코드 등록부에서 확인하세요. 해당 OpenAPI 버전을 지원하는 검증 도구로 문서 전체를 확인하고, 실제 API 응답과 비교하세요.

응답 키 예시

아래 예시는 응답 키의 형식과 의미를 구분해 검토하는 데 사용합니다. 필수 info 객체 등을 생략했으므로 완전한 OpenAPI 문서는 아닙니다. 두 번째 예시의 310도 그대로 사용할 것을 권장하지 않습니다.

잘못된 응답 키

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "50": {
            "description": "Invalid status"
          },
          "6xx": {
            "description": "Invalid range"
          }
        }
      }
    }
  }
}

의미 확인이 필요한 상태 코드

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

설명:

• 잘못된 응답 키: 50은 세 자리 상태 코드가 아니며 6xx는 허용되는 HTTP 상태 코드 범위가 아닙니다.
• 의미 확인이 필요한 상태 코드: 200은 요청 성공을 나타내지만, 310은 등록된 표준 리다이렉션 코드가 아닙니다. 실제 리다이렉션 동작에 맞는 301 또는 302 등의 코드를 선택해야 합니다.

참조

• OpenAPI 3.0.3 Responses Object
• OpenAPI 2.0 Responses Object
• IANA HTTP 상태 코드 등록부
• CWE-20