11. Declare Request Example Data
1. Declare Request Example Data
- 애플리케이션이 수신할 수 있는 데이터의 예시를 선언할 수 있다.
2. Pydantic schema_extra
Config및schema_extra를 사용하여 Pydantic 모델에 대한example을 선언할 수 있다.
from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[float] = None
class Config:
schema_extra = {
"example": {
"name": "Foo",
"description": "A very nice Item",
"price": 35.4,
"tax": 3.2,
}
}
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
results = {"item_id": item_id, "item": Item}
return results
- 해당 추가 정보는 해당 모델의 출력 JSON 스키마에 있는 그대로 추가되며 API 문서에서 사용된다.
- 위의 기능은 프론트엔드 사용자 인터페이스 등에 대한 메타데이터를 추가하는 데 사용할 수 있다.
3. Field additional arguments
- Pydantic 모델과 함께
Field()를 사용할 때, 다른 임의의 인수를 함수에 전달하여 JSON 스키마에 대한 추가 정보를 선언할 수도 있다.
- 다음과 같이 각 필드에 대한
example을 추가할 수 있다.
from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()
class Item(BaseModel):
name: str = Field(..., example="Foo")
description: Optional[str] = Field(None, example="A very nice Item")
price: float = Field(..., example=35.4)
tax: Optional[float] = Field(None, example=3.2)
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
results = {"item_id": item_id, "item": Item}
return results
Note
- 여기서 주의할 점은 전달된 추가 인수는 유효성 검사의 용도가 아닌 추가 정보를 제공하기 위한 용도로 사용된다.
4. example and examples in OpenAPI
- 다음 중 하나를 사용할 때 OpenAPI 추가될 추가 정보와 함께 데이터
example또는examples을 선언할 수도 있다.
1] Path()
2] Query()
3] Header()
4] Cookie()
5] Body()
6] Form()
7] File()
1) Body with example
- 다음의 예제는
Body()에서 예상되는 데이터의example을 전달하는 예제이다.
from typing import Optional
from fastapi import FastAPI, Body
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[float] = None
@app.put("/items/{item_id}")
async def update_item(
item_id: int,
item: Item = Body(
...,
example={
"name": "Foo",
"description": "A very nice Item",
"price": 35.4,
"tax": 3.2,
},
),
):
results = {"item_id": item_id, "item": item}
return results
2) Example in the docs UI
- 위의 예제를 실행하면,
/docs에서 다음과 같이 표시된다.
3) Body with multiple examples
- 단일
example대신 여러examples가 포함된dict를 사용하여 여러 예시를 전달할 수 있다. - 각
dict의 키는 각 예시를 식별하고, 각 값은 또 다른dict를 나타낸다. examples의 각 특정 예시dict에는 다음과 같은 키가 포함될 수 있다.
1] summary
- 예시에 대한 간단할 설명이다.
2] description
- Markdown 컨텍스트를 포함할 수 있는 긴 설명이다.
3] value
- 표시될 실제 예시이다.
4] externalValue
value의 대안으로, 예시를 가리키는 URL이다.
from typing import Optional
from fastapi import FastAPI, Body
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Optional[str] = None
price: float
tax: Optional[float] = None
@app.put("/items/{item_id}")
async def update_item(
item_id: int,
item: Item = Body(
...,
examples={
"normal": {
"summary": "A normal example",
"description": "A normal item works correctly.",
"value": {
"name": "Foo",
"description": "A very nice Item",
"price": 35.4,
"tax": 3.2,
},
},
"converted": {
"summary": "An example with converted data",
"description": "FastAPI can convert price `strings` to actual `numbers` automatically",
"value": {"name": "Bar", "price": "35.4"},
},
"invalid": {
"summary": "Invalid data is rejected with an error",
"value": {"name": "Baz", "price": "thirty five point four"},
},
},
),
):
results = {"item_id": item_id, "item": item}
return results
4) Examples in the docs UI
- 위의 예제를 실행하면,
/docs에서 다음과 같이 표시된다.
