[ FastAPI ] 요청 예시 데이터 선언

애플리케이션이 전달 받을 수 있는 데이터 예시를 선언할 수 있습니다.

 

그리고 이를 위한 여러 방법이 존재합니다.

 

Pydantic schema_extra

Pydantitc 공식 문서: 스키마 커스텀에 설명되어 있는, Config 와 schema_extra Pyndatntic 모델을 사용하여 example 을 선언할 수 있습니다:

 

 

추가 정보는 해당 모델의 JSON 스키마 결과로 그대로 추가되며, API 문서에 사용됩니다.

 

팁

JSON 스키마를 확장하고 본인만의 추가 정보를 추가할 때 똑같은 방법을 사용할 수 있습니다.

예를 들어 프론트엔드 유저 인터페이스를 위한 메타 데이터, 기타 등등을 추가하는 데 사용할 수 있습니다.

 

Field 추가 인자

Pydantic 모델과 함께 Field() 를 사용할 때, 다른 어떤 임의적인 인자를 함수에 전달하여 JSON 스키마에 추가적인 정보를 선언할 수 있습니다.

 

각 필드에 example 을 추가하여 사용할 수 있습니다:

 

 

주의

전달되는 추가 인자들은 어떤 유효성 검사도 없이, 단지 문서화의 목적만을 위한, 추가적인 정보라는 걸 명심하시기 바랍니다.

 

OpenAPI 속 example 과 examples

이것들 중 하나를 사용할 때:

 

• Path()
• Query()
• Header()
• Cookie()
• Body()
• Form()
• File()

 

OpenAPI에 추가되는 추가 정보를 데이터 example 또는 examples 의 그룹과 함께 선언할 수 있습니다.

 

example 을 사용한 Body

아래 예시는 Body() 에 예상되는 데이터의 example 을 전달합니다:

 

 

문서 UI 속 예시

위 방법 중 하나를 사용한 뒤 /docs 에 접근해보면 아래와 같이 보입니다:

 

 

다중 examples 를 사용한 Body

단일 example 대신, 다중 예시와 함께 dict 을 사용하여 OpenAPI에 각 추가 정보가 추가되는, examples 를 전달할 수 있습니다.

 

dict 의 키는 각 예시를 식별하고, 각 값이 또다른 dict 입니다.

 

examples 에 포함된 각각의 구체적인 예시 dict 은 아래와 같은 것들을 포함할 수 있습니다:

 

• summary : 예시에 대한 짧은 설명입니다.
• description : 마크다운 텍스트를 포함할 수 있는 긴 설명입니다.
• value : dict 과 같이, 보여질 실제 예시입니다.
• externalValue : value 대신, URL이 가리키는 예시입니다. 하지만 이는 value 만큼 많은 도구에서 지원되지 않을 수 있습니다.

 

 

문서 UI 속 예시

Body() 에 examples 을 추가한 뒤 /docs 에 접근해보면 아래와 같이 보입니다:

 

 

기술적 세부사항

주의

아래는 JSON 스키마와 OpenAPI 표준에 대한 기술적 세부사항입니다.

위 개념이 이미 충분하다면, 이러한 세부사항이 필요 없을 수 있기 때문에, 편하게 넘기셔도 좋습니다.

 

Pydantic 모델 내부에 예시를 추가할 경우, schema_extra 또는 Field(example="something") 을 사용하는 건 JSON 스키마 속 해당 Pydantic 모델에 대한 예시도 추가되는 걸 의미합니다.

 

그리고 해당 Pydantic 모델에 대한 JSON 스키마는 API의 OpenAPI에 포함되고, 문서 UI에 사용됩니다.

 

JSON 스키마는 표준 버전에서는 example 필드를 갖고 있지 않습니다. JSON 스키마의 최신 버전에서는 examples 필드를 정의하지만, OpenAPI 3.0.3은 examples 를 포함하지 않은 JSON 스키마 옛 버전을 기반으로 합니다.

 

따라서, OpenAPI 3.0.3은 동일한 목적을 위해 (그러나 examples 가 아닌, 단일 example 을 위해), JSON 스키마가 사용하는 수정된 버전을 위한 본인만의 example 을 정의하고, 이것이 바로 (Swagger UI가 사용하는) API 문서 UI에 의해 사용되는 방식입니다.

 

결국, example 은 JSON 스키마의 일부분이 아니더라도, OpenAPI의 JSON 스키마 커스텀 버전의 일부분이고, 이것이 문서 UI가 사용되는 방식입니다.

 

그러나 다른 유틸리티 ( Query() , Body() , 기타 등등 ) 와 함께 example 또는 examples 을 사용할 때 이러한 예시들은 데이터를 설명하는 JSON 스키마에 (심지어 JSON 스키마에 대한 OpenAPI 자체 버전에도) 추가되지 않고 (JSON 스키마를 사용한 OpenAPI의 외부 내용인) OpenAPI 속 경로 동작 선언에 곧바로 추가됩니다.

 

Path() , Query() , Header() , 그리고 Cookie() 에 대한, example 또는 examples 는 (명세서 속) Parameter Object 에 대한 OpenAPI 정의에 추가됩니다.

 

그리고 Body() , File() , 그리고 Form() 에 대한, example 또는 examples 는 (명세서 속) Request Body Object , content 필드 내부, Media Type Object 에 대한 OpenAPI 정의에 동일하게 추가됩니다.

 

한편, 최근에 배포된, 최신 OpenAPI 버전: 3.1.0이 있습니다. 최신 JSON 스키마를 기반으로 하고 최신 버전의 JSON 스키마 기능 대신 사용하던, OpenAPI의 JSON 스키마 커스텀 버전의 대부분의 수정 사항이 제거되어, 발생하던 작은 차이가 제거 됐습니다. 그럼에도 불구하고, Swagger UI는 현재 OpenAPI 3.1.0을 지원하지 않으므로, 현재는, 위 개념을 계속해서 적용하는 게 좋습니다.

 

---

원문

https://fastapi.tiangolo.com/tutorial/schema-extra-example/#body-with-multiple-examples

Declare Request Example Data - FastAPI