추가 상태 코드

추가 상태 코드 (Additional Status Codes)

기본적으로 FastAPI는 응답을 JSONResponse로 돌려줘요. 여러분이 path operation 에서 돌려준 내용을 그 JSONResponse 안에 넣어서 말이죠.

이때 사용하는 상태 코드는 기본값이거나, path operation 에서 여러분이 설정한 값이에요.

출처: 공식문서

추가 상태 코드 돌려주기

주요 상태 코드 외에 다른 상태 코드도 함께 돌려주고 싶다면, JSONResponse 같은 Response를 직접 돌려주고 그 안에서 원하는 추가 상태 코드를 설정하면 돼요.

예를 들어 항목을 업데이트할 수 있는 path operation 을 하나 만들고 싶다고 해볼게요. 성공했을 때는 HTTP 상태 코드 200 "OK"를 돌려주는 식으로요.

하지만 이 operation이 새 항목도 받아들이게 하고 싶다고 해봐요. 항목이 이전에 없었다면 새로 만들어서 HTTP 상태 코드 201 "Created"를 돌려주는 거예요.

이걸 하려면 JSONResponse를 임포트하고, 원하는 status_code를 설정해서 내용을 직접 돌려주면 돼요.

Python 3.10+

from typing import Annotated

from fastapi import Body, FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

items = {"foo": {"name": "Fighters", "size": 6}, "bar": {"name": "Tenders", "size": 3}}


@app.put("/items/{item_id}")
async def upsert_item(
    item_id: str,
    name: Annotated[str | None, Body()] = None,
    size: Annotated[int | None, Body()] = None,
):
    if item_id in items:
        item = items[item_id]
        item["name"] = name
        item["size"] = size
        return item
    else:
        item = {"name": name, "size": size}
        items[item_id] = item
        return JSONResponse(status_code=status.HTTP_201_CREATED, content=item)

경고

위 예시처럼 Response를 직접 돌려주면, 그 응답은 그대로 돌려줘요.

모델로 직렬화되거나 하지 않아요.

원하는 데이터가 그대로 담겨 있는지, 값이 유효한 JSON인지(JSONResponse를 사용한다면) 확인해야 해요.

기술적 세부 사항

from starlette.responses import JSONResponse를 쓸 수도 있어요.

FastAPI가 starlette.responses를 fastapi.responses로 동일하게 제공하는 건 개발자(여러분)를 위한 편의일 뿐이에요. 대부분의 응답은 실제로 Starlette에서 바로 온 거예요. status도 마찬가지고요.

OpenAPI와 API 문서

추가 상태 코드와 응답을 직접 돌려주면, 그 응답들은 OpenAPI 스키마(API 문서)에 포함되지 않아요. FastAPI는 여러분이 무엇을 돌려줄지 미리 알 방법이 없기 때문이에요.

하지만 코드에서 이를 문서화할 수 있어요. 바로 추가 응답 장을 사용해서요.

더 알아보기 (Learn more)

이 문서는 FastAPI 공식 문서 - Additional Status Codes를 한국어로 정리한 번역이에요. 원문에서 최신 내용과 더 다양한 예시를 확인하세요.