설명
HTTP 헤더 이름은 대소문자를 구분하지 않습니다. 같은 요청에서 token과 Token처럼 표기만 다른 이름을 별개의 헤더로 정의하면 서로 다른 값을 전달할 수 있다고 오해할 수 있습니다.
잠재적 영향
문서와 생성 클라이언트가 같은 헤더를 중복 관리하거나 서로 다른 의미로 처리해 요청 연동이 어긋날 수 있습니다.
해결 방법
같은 요청에 적용되는 헤더는 하나의 일관된 정의로 관리하세요. 별도의 값이 필요하면 실제 API가 구분하는 다른 이름을 사용하세요. 재사용 정의 목록 자체의 유사한 항목과, 한 요청에 동시에 적용되는 중복은 구분하세요.
예시
OpenAPI 3.0의 경로 파라미터 목록 발췌입니다. info와 실제 작업은 생략했으며 인증 설정 전체를 보여주는 예시는 아닙니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"parameters": [
{
"name": "token",
"in": "header",
"schema": {
"type": "string"
}
},
{
"name": "Token",
"in": "header",
"schema": {
"type": "string"
}
}
]
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"parameters": [
{
"name": "token",
"in": "header",
"schema": {
"type": "string"
}
},
{
"name": "username",
"in": "header",
"schema": {
"type": "string"
}
}
]
}
}
}
변경 전의 token과 Token은 HTTP에서 같은 헤더 이름입니다. 변경 후의 username은 서버가 실제로 별도의 사용자 이름 헤더를 받는 경우에만 적절합니다. 같은 토큰을 뜻한다면 두 번째 정의를 제거하세요.