[ FastAPI ] 요청 바디

클라이언트로부터 (브라우저라 가정해봅시다) 당신의 API로 데이터를 보내야 할 때, 요청 바디로 보낼 수 있습니다.

 

요청 바디는 클라이언트가 API로 전달하는 데이터입니다. 응답 바디는 API가 클라이언트로 전달하는 데이터입니다.

 

API는 거의 항상 응답 바디를 보내야 합니다. 하지만 클라이언트는 매번 의무적으로 요청 바디를 보낼 필요가 없습니다.

 

요청 바디를 선언하기 위해, Pydantic 모델의 기능과 이점을 사용할 수 있습니다.

 

정보
데이터를 보내기 위해, 다음 중 하나를 사용해야 합니다: (주로 사용되는) POST , PUT , DELETE 또는 PATCH .

GET 요청과 함께 바디를 전달하는 건 명세서에 정의되지 않은 행동이지만, 그럼에도 불구하고, 복잡하고/극단적인 사용 사례을 위해 FastAPI에서는 이를 지원해줍니다.

별로 장려되지 않기 때문에, Swagger UI를 통한 대화형 문서는 GET 을 사용했을 때 바디를 문서에 보여주지 않고, 중간에 위치한 프록시가 지원되지 않습니다.

 

Pydantic의 BaseModel 임포트

우선, pydantic 으로부터 BaseModel 을 임포트해야 합니다:

 

 

데이터 모델 생성

이제 BaseModel 을 상속 받는 데이터 모델을 클래스로 선언해야 합니다.

 

모든 어트리뷰트에는 표준 파이썬 자료형을 사용하시면 됩니다:

 

 

쿼리 매개변수를 선언했을 때와 동일하게, 모델 어트리뷰트가 기본 값을 가지면, 값이 필수적으로 요구되지 않습니다.

 

이와 반대되는 경우, 요구됩니다. 단지 선택사항으로 만들기 위해서는 None 을 사용하시기 바랍니다.

 

예를 들어, 위 모델은 JSON " object " (또는 파이썬 dict )을 다음과 같이 선언합니다:

 

 

... description 과 tax 가 ( None 을 기본 값으로 하는) 선택 사항이기 때문에, 아래와 같은 JSON " object " 도 유효합니다:

 

 

매개변수로 선언

경로 동작에 추가하기 위해, 경로와 쿼리 매개변수를 선언했던 것과 같은 방식을 사용하시기 바랍니다:

 

 

... 그리고 만든 모델인, Item 으로 그 자료형을 선언하면 됩니다.

 

결론

이러한 파이썬 자료형 선언을 통해, FastAPI는 다음과 같이 동작합니다:

 

• 요청 바디를 JSON으로 읽습니다.
• (만약 필요하다면) 해당하는 자료형으로 변환시킵니다.
• 데이터 유효성 검사를 진행합니다.
  • 만약 데이터가 유효하지 않다면, 멋지고 명백한 오류를 반환하고, 어디서 어떤 올바르지 않은 데이터가 발생했는지 알려줍니다.
• 매개변수 item 에 전달하는 데이터를 전달합니다.
  • 이것을 자료형 Item 으로 함수 안에 선언했기 때문에, 모든 어트리뷰트와 자료형에 대한 (자동완성, 기타 등등과 같은) 편집기의 지원을 받을 수 있습니다.
• 모델의 JSON 스키마 정의를 생성하고, 또한 프로젝트에 적합하다면 원하는 다른 곳에도 사용할 수 있습니다.
• 이러한 스키마는 생성된 OpenAPI 스키마의 부분이 되고, 자동 문서 UI로도 사용됩니다.

 

자동 문서

모델의 JSON 스키마는 OpenAPI 생성 스키마의 일부가 되고, 대화형 API 문서에도 보여집니다:

 

 

또한 이것을 필요로 하는 각 경로 동작 내부의 API 문서에도 사용됩니다:

 

 

편집기의 지원

편집기를 통해, 함수 내부에서 자료형 힌트와 자동 완성을 어디서든 지원받을 수 있습니다 (만약 Pydantic 모델 대신 dict 을 전달했다면 지원되지 않습니다.):

 

 

또한 부정확한 자료형 작업에 대한 오류 확인도 할 수 있습니다:

 

 

이것은 우연이 아니고, 전체 프레임워크가 이러한 디자인으로 설계되었기 때문입니다.

 

그리고, 구현하기 전에, 모든 편집기에서 동작되도록 디자인 단계에서 철저하게 테스트 되었습니다.

 

심지어 이것을 위해 Pydantic 스스로도 약간의 변화가 있었습니다.

 

이전 스크린샷은 Visual Studio Code 를 캡처했습니다.

 

그러나 PyCharm 및 대부분의 다른 파이썬 편집기를 사용해도 동일한 편집기의 지원을 받을 수 있습니다:

 

 

팁
PyCharm 을 편집기로 사용한다면, Pydantic PyCharm Plugin 을 사용할 수 있습니다.

이것은 Pydantic 모델을 위해, 다음과 같은 편집기의 지원을 향상시켜줍니다:

- 자동-완성
- 자료형 확인
- 리팩토링
- 검색
- 검사

 

모델 사용

함수 내부에서, 모델 객체의 모든 어트리뷰트에 바로 접근할 수 있습니다:

 

 

 

요청 바디 + 경로 매개변수

경로 매개변수와 요청 바디를 동시에 선언할 수 있습니다.

 

FastAPI는 경로 매개변수와 일치하는 함수 매개변수를 경로에서 가져와야 하고, Pydantic 모델로 선언된 함수 매개변수가 요청 바디에서 가져와야 한다는 걸 인식합니다.

 

 

요청 바디 + 경로 + 쿼리 매개변수

또한 바디, 경로 그리고 쿼리 매개변수를 동시에 선언할 수 있습니다.

 

FastAPI는 그것을 각각 인지하고 올바른 위치에서 가져옵니다.

 

 

함수 매개변수는 다음과 같이 인지됩니다:

 

• 만약 매개변수가 경로에도 선언되었다면, 경로 매개변수로 사용됩니다.
• 만약 매개변수가 ( int , float , str , bool , 기타 등등의) 단일 자료형이라면 쿼리 매개변수로 해석됩니다.
• 만약 매개변수가 Pydantic 모델의 자료형으로 선언되었다면, 요청 바디로 해석됩니다.

 

노트
FastAPI는 기본 값이 = None 이기 때문에 q 의 값이 필수로 요구되지 않는다는 걸 알게 됩니다.

Optional[str] 속 Optional 은 FastAPI에 의해 사용되지 않지만 (FastAPI는 오로지 str 부분만 사용합니다), Optional[str] 은 편집기가 코드 속 오류를 찾는 데 도움을 줍니다.

 

Pydantic을 사용하지 않는 방법

만약 당신이 Pydantic 모델을 사용하지 않길 원하더라도, Body 매개변수를 사용할 수 있습니다. 바디 - 다중 매개변수: 바디 속 단일 값들 문서를 확인하시기 바랍니다.