22. Path Operation Configuration

---

1. Path Operation Configuration

• path operation 데코레이터에 전달하여 구성할 수 있는 몇 가지 매개변수가 있다.

2. Response Status Code

• path operation의 response에 사용할 (HTTP) status_code를 정의할 수 있다.
• 404와 같은 int 타입의 코드를 직접 전달할 수 있다.

• 하지만 각 숫자 코드의 용도가 기억나지 않는 경우 다음과 같이 status에서 해당 숫자 코드를 가져와 사용할 수 있다.

from typing import Optional, Set
from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None
    tags: Set[str] = set()

@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item

3. Tags

• path operation에 태그를 추가하고 str 타입의 list와 함께 매개변수 tags를 전달할 수 있다.

from typing import Optional, Set
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
    tags: Set[str] = set()

@app.post("/items/", response_model=Item, tags=["items"])
async def create_item(item: Item):
    return item

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]

@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

• 위의 예제를 실행하면 다음과 같이 확인된다.

4. Summary and description

• summary와 description을 추가할 수 있다.

from typing import Optional, Set
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
    tags: Set[str] = set()

@app.post(
    "/items/",
    response_model=Item,
    summary="Create an item",
    description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item):
    return item

5. Description from docstring

• 일반적으로 설명이라는 것은 길고 여러 줄을 포함하는 경향이 있으므로, docstring으로 path operation의 설명을 선언하는 방법도 좋다.

from typing import Optional, Set
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
    tags: Set[str] = set()

@app.post("/items/", response_model=Item, summary="Create an item")
async def create_item(item: Item):
    """
    Create an item with all the information:

    - name: each item must have a name
    - description: a long description
    - price: required
    - tax: if the item doesn't have tax, you can omit this
    - tags: a set of unique tag strings for this item
    """

    return item

• 위의 예제를 실행하면 다음과 같이 확인된다.

6. Response description

• response_description 매개변수를 사용하여 response 설명을 지정할 수 있다.

from typing import Optional, Set
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
    tags: Set[str] = set()

@app.post(
    "/items/",
    response_model=Item,
    summary="Create an item",
    response_description="The created item",
)
async def create_item(item: Item):
    """
    Create an item with all the information:

    - name: each item must have a name
    - description: a long description
    - price: required
    - tax: if the item doesn't have tax, you can omit this
    - tags: a set of unique tag strings for this item
    """

    return item

• 위의 예제를 실행하면 다음과 같이 확인된다.

7. Deprecate a path operation

• 어떠한 path operation을 서버에서 더 이상 사용하지 않는 경우 deprecated 매개변수를 전달하면 된다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]

@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
    return [{"item_id": "Foo"}]

• 위의 예제를 실행하면 다음과 같이 확인된다.

• 사용하는 것과 사용하지 않는 path operations는 각각 다음과 같이 확인된다.

---

References

• https://fastapi.tiangolo.com/tutorial/path-operation-configuration/