경로 조작 설정 (Path Operation Configuration)

경로 조작 설정 (Path Operation Configuration)

_경로 조작 데코레이터_에 넘겨서 동작을 설정할 수 있는 매개변수가 몇 가지 있어요. 이 페이지에서 하나씩 살펴볼게요.

주의

이 매개변수들은 _경로 조작 함수_가 아니라 **경로 조작 데코레이터**에 직접 전달된다는 점을 꼭 기억하세요.

응답 상태 코드 (Response Status Code)

_경로 조작_의 응답에 사용할 (HTTP) status_code를 직접 지정할 수 있어요.

404처럼 숫자 int 코드를 그대로 넘겨도 돼요. 그런데 각 번호가 뭘 의미하는지 매번 기억하기 어렵다면, status에 준비된 상수(shortcut constant)를 쓰면 훨씬 편해요.

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()

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

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

이 상태 코드는 응답에 사용되고, OpenAPI 스키마에도 함께 추가돼요.

기술 세부사항

from starlette import status로 가져와서 써도 돼요.

FastAPI는 개발자 편의를 위해 starlette.status와 같은 값을 fastapi.status로도 제공할 뿐이에요. 실제로는 Starlette에서 온 거예요.

태그 (Tags)

_경로 조작_에 태그를 추가할 수 있어요. tags 매개변수에 str의 list를 넘기면 되는데, 보통은 str 하나만 담아서 넘겨요.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.post("/items/", tags=["items"])
async def create_item(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"}]

태그는 OpenAPI 스키마에 추가되고, 자동 문서 인터페이스에서도 사용돼요.

Enum으로 태그 관리하기 (Tags with Enums)

앱이 커지다 보면 태그가 여러 개 쌓일 수 있어요. 관련된 _경로 조작_에는 항상 같은 태그를 쓰고 싶을 때가 많은데요, 그럴 때는 태그를 Enum으로 정리해 두는 게 한 가지 방법이에요.

FastAPI는 일반 문자열과 똑같은 방식으로 Enum 태그를 지원해요.

from enum import Enum

from fastapi import FastAPI

app = FastAPI()

class Tags(Enum):
    items = "items"
    users = "users"

@app.get("/items/", tags=[Tags.items])
async def get_items():
    return ["Portal gun", "Plumbus"]

@app.get("/users/", tags=[Tags.users])
async def read_users():
    return ["Rick", "Morty"]

요약과 설명 (Summary and description)

_경로 조작_에 summary와 description을 추가할 수 있어요.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.post(
    "/items/",
    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) -> Item:
    return item

docstring에서 설명 가져오기 (Description from docstring)

설명은 길어지고 여러 줄에 걸치는 경우가 많아요. 그럴 때는 함수의 docstring에 경로 조작 설명을 적어 두면 FastAPI가 거기서 읽어와요.

docstring 안에는 Markdown을 쓸 수 있고, 해석되어 올바르게 표시돼요. (docstring의 들여쓰기도 고려해요.)

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.post("/items/", summary="Create an item")
async def create_item(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

이 내용은 대화형 문서(interactive docs)에서 사용돼요.

응답 설명 (Response description)

응답에 대한 설명은 response_description 매개변수로 지정할 수 있어요.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.post(
    "/items/",
    summary="Create an item",
    response_description="The created item",
)
async def create_item(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

참고

response_description는 말 그대로 응답에 대한 설명이고, description은 경로 조작 자체에 대한 설명이에요. 둘은 가리키는 대상이 달라요.

팁

OpenAPI 명세는 각 _경로 조작_이 응답 설명을 반드시 가지도록 요구해요. 그래서 따로 지정하지 않으면 FastAPI가 자동으로 "Successful response"라는 응답 설명을 만들어 넣어요.

경로 조작 폐기하기 (Deprecate a path operation)

_경로 조작_을 실제로 제거하지는 않고 '더 이상 쓰지 않음(deprecated)'으로 표시하고 싶을 때가 있어요. 그럴 때 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"}]

대화형 문서에서 이 _경로 조작_은 명확하게 'deprecated'로 표시돼요.

정리 (Recap)

_경로 조작 데코레이터_에 매개변수를 넘기기만 하면, _경로 조작_을 쉽게 설정하고 메타데이터를 추가할 수 있어요.