[ FastAPI ] 응답 모델

모든 경로 동작 내부에 매개변수 response_model 을 사용하여 응답을 위한 모델을 선언할 수 있습니다:

 

• @app.get()
• @app.post()
• @app.put()
• @app.delete()
• 기타 등등.

 

 

참고

response_model 은 모든 매개변수 및 바디와 같이, 경로 동작 함수가 아닌 "데코레이터" 메서드 ( get , post , 기타 등등)의 매개변수인 것을 잊지마시기 바랍니다. 

 

Pydantic 모델 어트리뷰트를 위해 선언했던 것과 동일한 자료형을 전달 받기 때문에, Pydnatic 모델이 되지만, List[Item] 과 같은, 예를 들어 Pydantic 모델의 list 가 될 수도 있습니다.

 

FastAPI는 이 response_model 을 다음을 위해 사용합니다:

 

• 각 자료형 선언에 따른 결과 데이터 전환
• 데이터 유효성 검사
• OpenAPI 속 경로 동작에, 응답을 위한 JSON 스키마 추가
• 자동 문서화 시스템에 의한 사용

 

그러나 가장 중요한 건 다음과 같습니다:

 

• 모델의 결과 데이터를 제한합니다. 이것이 얼마나 중요한 지 아래에서 살펴볼 것입니다.

 

기술적 세부사항

응답 모델은 경로 함수가 실제로 응답 모델을 반환하지 않고 dict , 데이터베이스 객체 또는 다른 모델을 반환하고, response_model 을 필드 제한과 직렬화 작업에 사용하기 때문에, 함수의 반환 자료형 어노테이션 대신 매개변수 내부에 선언됩니다.

 

동일한 입력 데이터 반환

여기 선언한 UserIn 모델이 존재하며, 숨김 없는 텍스트 비밀번호를 포함합니다:

 

 

그리고 이 모델을 입력과 출력을 위해 동일하게 사용합니다:

 

 

이제, 브라우저가 비밀번호와 함께 사용자를 생성할 때마다, API는 응답에 동일한 비밀번호를 반환합니다.

 

이 경우, 사용자 스스로 비밀번호를 보내기 때문에, 문제가 되지 않습니다.

 

그러나 다른 경로 동작에 동일한 모델을 하용한다면, 모든 클라이언트에게 사용자의 비밀번호를 보내게 됩니다.

 

위험

절대 사용자의 숨김 없는 비밀번호는 저장하지 말고 또는 응답으로 보내지 마시기 바랍니다.

 

결과 모델 추가

대신에 숨김 없는 비밀번호를 사용한 입력 모델을 생성하고 결과 모델에는 이를 제외할 수 있습니다:

 

 

여기, 경로 동작 함수가 비밀번호를 포함한 동일한 입력 사용자를 반환하더라도:

 

 

...비밀번호를 포함하지 않은, 모델 UserOut 이 되는 response_model 을 선언할 수 있습니다:

 

 

따라서, FastAPI는 (Pydantic을 사용하여) 출력 모델에 선언되지 않은 데이터를 전부 여과합니다.

 

문서 확인

자동 문서를 보면, 입력 모델과 출력 모델이 모두 각자의 JSON 스키마를 갖고 있은 것을 확인할 수 있습니다:

 

 

그리고 두 모델은 대화형 API 문서를 위해 사용됩니다:

 

 

응답 모델 부호화 매개변수

응답 모델이 다음과 같이, 기본 값을 가질 수 있습니다:

 

 

• description : Optional[str] = None 은 None 이라는 기본 값을 갖습니다.
• tax: float = 10.5 는 10.5 라는 기본 값을 갖습니다.
• tags: List[str] = [] 은 빈 리스트: [] 라는 기본 값을 갖습니다.

 

그러나 실제로 저장되지 않은다면 결과로부터 생략하고 싶을 수 있습니다.

 

예를 들어, NoSQL 데이터베이스에 많은 선택적 어트리뷰트를 가진 모델이 있지만, 기본 값이 전부 포함된 아주 긴 JSON 응답을 전달하지 않기를 원할 수 있습니다.

 

response_model_exclude_unset 매개변수 사용

경로 동작 데코레이터 매개변수 response_model_exclude_unset=True 를 설정할 수 있습니다:

 

 

그리고 이러한 기본 값들은 실제로 설정된 값이 아니면, 응답에 포함되지 않습니다.

 

따라서, 만약 ID foo 를 가진 아이템을 경로 동작에 요청할 경우, 응답은 (기본 값을 포함하지 않고) 아래와 같습니다:

 

 

정보

FastAPI는 이를 달성하기 위해 Pydantic 모델의 .dict() 을 exclude_unset 매개변수와 함께 사용합니다.

 

정보

물론 다음을 사용할 수도 있습니다:

- response_model_exclude_defaults=True
- response_model_exclude_none=True

Pydantic 공식 문서에 exclude_defaults 및 exclude_none 을 위한 설명이 작성 되어있습니다.

 

기본 값을 사용하는 필드를 위한 값의 데이터

그러나 데이터가 아래와 같이 ID bar 를 사용하는 아이템처럼, 기본 값을 가진 모델의 필드를 위한 값을 가질 수 있습니다.

 

 

이것들은 응답 내에 포함됩니다.

 

기본 값으로 동일한 값을 사용하는 데이터

데이터가 아래와 같이 ID baz 를 사용하는 아이템처럼, 기본 값으로 동일한 값을 사용하는 데이터일 수 있습니다:

 

 

FastAPI는 description , tax , 그리고 tags 가 기본 값으로 동일한 값을 갖더라도, (기본 값으로부터 값을 가져오는 것이 아닌) 명시적으로 설정되는 것을 알아차릴 정도로 (사실, Pyndatic이 충분히 똑똑한 것이지만) 충분히 똑똑합니다.

 

그래서, JSON 응답에 포함됩니다.

 

팁

None 뿐만 아니라 어떤 것이라도 기본 값이 될 수 있다는 걸 잊지마시기 바랍니다.

리스트( [] ), 10.5 와 같은 float , 기타 등등이 될 수 있습니다.

 

response_model_include 와 response_model_exclude

경로 동작 데코레이터 매개변수를 response_model_include 와 response_model_exclude 에도 사용할 수 있습니다.

 

이것들은 어트리뷰트의 이름을 사용한 str 의 set 을 가지고 (나머지를 생략하고) 포함하거나 (나머지를 포함하고) 제외합니다.

 

만약 단 하나의 Pydantic 모델을 가지고 있고 출력으로부터 몇몇의 데이터를 삭제하고 싶다면 이 방법은 가장 빠른 지름길이 되어줄 것입니다.

 

팁

그러나 여전히 이러한 매개변수 대신, 다중 클래스를 사용하는, 맨 위의 개념이 권장됩니다.

왜냐하면 OpenAPI (그리고 문서) 속에 생성된 JSON 스키마가 몇몇의 어트리뷰트를 생략하기 위해 response_model_include 또는 response_model_exclude 를 사용한다고 하더라도, 여전히 온전한 모델을 위한 것이기 때문입니다.

이것은 유사하게 작동하는 response_model_by_alias 에도 적용되는 이야기입니다.

 

 

팁

문법 {"name", "description"} 은 두 값을 사용하여 set 을 생성합니다.

이것은 set(["name", "description"]) 과 동일한 방법입니다.

 

set 대신 list 사용

set 을 사용하는 것을 잊어 list 또는 tuple 을 대신 사용한다면, FastAPI는 이것을 set 으로 변환하고 올바르게 작동시킵니다:

 

 

요약

응답 모델을 정의하고 특별히 개인적 데이터의 여과를 확실히하기 위해 경로 동작 데코레이터의 매개변수 response_model 을 사용하면 됩니다.

 

명시적으로 설정된 값만 반환하기 위해 response_model_exclude_unset 를 사용하면 됩니다.

 

---

원문

https://fastapi.tiangolo.com/tutorial/response-model/

Response Model - FastAPI