FastAPI - example

사용자가 어떤 값을 보내야하는지를 확인하려면 Swagger UI와 같은 문서를 통해서 확인이 가능할 것이다.

그런데 구체적으로 값을 어떤형태로 어떻게 구성을 해야지 서버측에서 정상적으로 값을 받는지를 알아야지만 보내기 수월할 것이다

이때 사용되는것이 example이다

1. example

이렇게 모델이 선언되어 있을때 model_config의 값으로 json_schema_extra의 값에 example값을 넣고 그 내부에 예시가 될만한 형태의 값을 넣어주면 된다

예시를 보여주자면

이런식으로 설정하면 된다.

 

그리고 이제 함수 하나를 생성해서 맵핑을 해주면

 

Swagger UI의 Schemas에 모델 아래에 Example을 확인할 수 있다.

 

2. 모델의 요소에 직접 다는 example

위는 전체 모델에 대한 example이고 하나 하나 멤버마다 달아줄 수 도 있다.

이 때는 Field의 속성중 examples의 값을 배열로 넣어주면 

이렇게 요소 하나하나에 각각 example이 확인이 가능하다.

 

이렇게 example을 설정할 수 있는 요소는 Path(), Query(), Header(), Cookie(), Body(), Form(), File()에 설정이 가능하다

 

3. example을 포함한 Body()

이렇게 구성되어 있는 상태에서 Body를 통해서 example을 설정할 수 도 있다.

먼저 Annotated를 import하고 

이렇게 Annotated를 설정하고 첫번째 인자로는 모델의 타입을 두번째로는 Body()를 넣어준다.

그리고 Body의 내부에 examples를 사용해서 배열로 객체의 예시를 넣어주면

이렇게 FastAPI의 Swagger UI에서 파라미터에 대한 예시를 확인할 수 있게 된다.

 

4. Body의 openapi_examples

body에는 openapi_examples라는 요소로 값을 넣을 수 있는데 예시를 한번 보면서 확인해보도록 하자.

먼저 모델이 아래와 같이 구성되었을때

이 openapi_examples는 아래와 같이 구성될 수 있다.

이렇게 구성되면 openapi_examples내부의 첫번째 depth의 normal, convert, error은 각자의 값을 구분하는 key에 대한 내용으로 사실은 크게 의미 있는 값은 아니고 관리자가 이를 관리할때 해당 값들은 뭘 위한 것에 대해서 한번에 알 수 있게 설정하는 간단한 명칭이라고 보면 된다.

그리고 그내부의 summery는 해당 예시에 대한 간단한 설명, description은 해당 예시에 대한 구체적인 설명, value는 예시값을 넣어준다

우리가 넣은 summer는 아래와 같이 Examples의 항목으로 드롭박스 내부에 리스트로 나온다.

그리고 이에 대한 각각의 예시는 

우리가 넣은 value가 확인된다.

그리고 그 밑에 이 예시에 대한 구체적인 설명이 들어간다.

 

이렇게 해당 요소들이 어떤식으로 들어올때 까지 정상적으로 처리를 해주는지 어떤 형태가 들어오면 안되는 지에 대해서 작성해줄 수 있는 부분이라고 보면된다.

 

# 해당 부분은 옛날 FastAPI에서는 이런식으로 example을 구성했다 정도로 이해하면 될 듯 싶다...