- 에러 일시 : 2025-04-22
- 에러 유형 : FastAPI 의 x-www-form-urlencoded 형태의 Request Body 를 받는 Post 메소드 요청 테스트 에서 fastapi.Form 설정의 alias 가 Swagger 에서 동작하지 않는 문제 발생
(에러 상세)
1. 에러 발생 코드
@router.post(
"/post-request-x-www-form-urlencoded",
response_model=model.PostRequestTestWithFormTypeRequestBodyOutputVo,
summary="Post 요청 테스트 (x-www-form-urlencoded)",
description="x-www-form-urlencoded 형태의 Request Body 를 받는 Post 메소드 요청 테스트"
)
async def post_request_test_with_form_type_request_body(
request_form_string: str =
fastapi.Form(
...,
alias="requestFormString",
description="String Form 파라미터",
example="testString"
),
request_form_string_nullable: typing.Optional[str] =
fastapi.Form(
None,
alias="requestFormStringNullable",
description="String Nullable Form 파라미터",
example="testString"
),
request_form_int: int =
fastapi.Form(
...,
alias="requestFormInt",
description="Int Form 파라미터",
example=1
),
request_form_int_nullable: typing.Optional[int] =
fastapi.Form(
None,
alias="requestFormIntNullable",
description="Int Nullable Form 파라미터",
example=1
),
request_form_double: float =
fastapi.Form(
...,
alias="requestFormDouble",
description="Double Form 파라미터",
example=1.1
),
request_form_double_nullable: typing.Optional[float] =
fastapi.Form(
None,
alias="requestFormDoubleNullable",
description="Double Nullable Form 파라미터",
example=1.1
),
request_form_boolean: bool =
fastapi.Form(
...,
alias="requestFormBoolean",
description="Boolean Form 파라미터",
example=True
),
request_form_boolean_nullable: typing.Optional[bool] =
fastapi.Form(
None,
alias="requestFormBooleanNullable",
description="Boolean Nullable Form 파라미터",
example=True
),
request_form_string_list: typing.List[str] =
fastapi.Form(
...,
alias="requestFormStringList",
description="StringList Form 파라미터",
example=["testString1", "testString2"]
),
request_form_string_list_nullable: typing.Optional[typing.List[str]] =
fastapi.Form(
None,
alias="requestFormStringListNullable",
description="StringList Nullable Form 파라미터",
example=["testString1", "testString2"]
)
):
return await service.post_request_test_with_form_type_request_body(
request_form_string,
request_form_string_nullable,
request_form_int,
request_form_int_nullable,
request_form_double,
request_form_double_nullable,
request_form_boolean,
request_form_boolean_nullable,
request_form_string_list,
request_form_string_list_nullable
)
위와 같은 예시에서, Form 데이터 설정에 분명 alias 를 넣었지만 Swagger 문서상으론,
위와 같이 alias 가 적용되지 않음.
API 실행시,
422 에러 발생.
2. 에러 분석
curl -X 'POST' \
'http://127.0.0.1:8080/api-test/post-request-x-www-form-urlencoded' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'request_form_string_list=string&request_form_boolean_nullable=true&request_form_int=0&request_form_string_nullable=string&request_form_double_nullable=0&request_form_double=0&request_form_string=string&request_form_int_nullable=0&request_form_boolean=true&request_form_string_list_nullable=string'
위와 같이 curl 명령어가 보내짐.
swagger api 상에 보이듯 alias 가 적용되지 않은 변수명으로 요청을 보낸 것이 문제로 추정.
(문제 해결)
1. 가장 단순한 방식
alias 제거 후 request_form_string 와 같은 python 변수명 규칙을 그대로 따르는 것을 고려.
하지만, 이 방식은 API 자유도를 떨어뜨리는 방식으로, 외부에서 강하게 요청시 변수명을 바꿔야 하는 문제가 있음.
Camel 표기법은 문제가 안되지만, Kebab 표기법의 경우 변수명으로 지정하지 못하는 치명적인 단점 존재
2. validation_alias 설정 추가
여러 해결법을 검색했지만 정답이 나오지 않고 chat gpt 역시 답을 내놓지 못하는 상황.
공식 홈페이지에도 관련된 내용을 쓰여있지 않은 상태에서 여러 시도.
결국 Form 클래스 내의 설정 변수를 하나씩 살펴보다가 alias 관련 또다른 변수들을 발견.
이것을 적용하며 테스트 하던 중,
alias 와 validation_alias 를 동시에 사용하면 문제가 해결됨을 발견.
request_form_string: str =
fastapi.Form(
...,
alias="requestFormString",
validation_alias="requestFormString",
description="String Form 파라미터",
example="testString"
),
위와 같은 방식으로 alias 와 동일한 값으로 validation_alias 설정을 추가.
결과, 위와 같이 Swagger 변수명 표기 및 curl 요청시 alias 적용 처리 완료를 확인.
문제의 원인은 Swagger 에서 alias 를 기준으로 변수명을 잡는 것이 아니라, Form 클래스에 한해 validation_alias 를 기준으로 삼고 있는 것으로 보임.
명백한 라이브러리 에러로 보이며, 추후 fix 될 가능성이 있으므로 주시할것.