[FastAPI 공식문서] FastAPI - (5) 경로 매개변수와 데이터 검증

🏖️ FastAPI에서 경로 매개변수 처리하기

1. 경로 매개변수 (Path Parameters)

경로 매개변수는 URL의 특정 부분에서 데이터를 추출하여 처리하는 방식입니다. FastAPI는 파이썬의 포맷 문자열 문법을 사용하여 이를 지원합니다.

1.1 기본 사용법

경로 매개변수를 사용하려면, URL에서 중괄호 {} 안에 변수명을 작성합니다. FastAPI는 해당 변수명을 함수 인자로 전달합니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    return {"item_id": item_id}

위 코드에서:

• /items/{item_id}는 경로 매개변수 item_id를 URL에서 추출합니다.
• URL 예시: http://127.0.0.1:8000/items/foo에서 foo가 item_id로 전달되고, 클라이언트는 {"item_id": "foo"}라는 JSON 응답을 받습니다.

1.2 파이썬의 타입 어노테이션 사용

경로 매개변수에 타입을 지정하여 데이터 타입을 제한할 수 있습니다. FastAPI는 이 타입 정보를 기반으로 데이터 검증과 변환을 자동으로 처리합니다.

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

• 이 예시에서는 item_id가 정수(int) 타입이어야 합니다.
• URL http://127.0.0.1:8000/items/3로 접속하면 {"item_id": 3}이라는 응답을 받습니다.
• 만약 http://127.0.0.1:8000/items/foo처럼 문자열을 넣으면, FastAPI는 자동으로 검증 오류를 반환합니다.

1.3 데이터 검증

FastAPI는 경로 매개변수의 타입이 맞지 않을 때 자동으로 검증 오류를 반환합니다. 예를 들어, item_id가 정수로 선언되었으나 문자열이 입력된 경우:

{
  "detail": [
    {
      "loc": ["path", "item_id"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

• FastAPI는 정확히 어느 경로에서 문제가 발생했는지, 어떤 데이터 타입 오류가 있는지 명시해줍니다. 이를 통해 개발자는 즉시 문제를 파악하고 해결할 수 있습니다.

---

2. 경로 매개변수의 타입 변환과 자동 문서화

2.1 데이터 변환

FastAPI는 경로 매개변수를 파싱하여 지정한 데이터 타입으로 자동 변환합니다. 예를 들어, URL에 입력된 값은 문자열이지만, FastAPI는 이를 정수로 변환합니다.

• URL: http://127.0.0.1:8000/items/3
• 응답: {"item_id": 3}

이 때 3은 문자열로 전달되지만, FastAPI는 이를 int로 변환하여 처리합니다.

2.2 자동 문서화

경로 매개변수에 타입 어노테이션을 추가하면 FastAPI는 자동으로 API 문서를 생성합니다.

• http://127.0.0.1:8000/docs: Swagger UI 기반의 대화형 문서가 제공되며, 경로 매개변수와 그 타입을 자동으로 표시합니다.
• http://127.0.0.1:8000/redoc: ReDoc을 사용한 대체 문서가 제공됩니다.

3. 경로 매개변수의 고정 값 사용 (Enum)

경로 매개변수로 가능한 값을 미리 정의하고 제한하고 싶다면 Enum을 사용할 수 있습니다. 이를 통해 특정 값만 허용할 수 있습니다.

3.1 Enum 클래스 사용

from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}
    elif model_name is ModelName.lenet:
        return {"model_name": model_name, "message": "LeCNN all the images"}
    return {"model_name": model_name, "message": "Have some residuals"}

• ModelName이라는 Enum 클래스를 정의하여 가능한 경로 매개변수 값을 제한했습니다.
• http://127.0.0.1:8000/models/alexnet와 같은 요청은 {"model_name": "alexnet", "message": "Deep Learning FTW!"}라는 응답을 반환합니다.
• 만약 alexnet, resnet, lenet 외의 값을 입력하면 FastAPI는 오류를 반환합니다.

3.2 Enum의 이점

• Enum을 사용하면 경로 매개변수의 값을 제한할 수 있으며, 해당 값들이 API 문서에 자동으로 표시됩니다.
• 자동 문서화와 함께 API를 호출하는 사용자에게 허용된 값의 목록을 명확하게 제공합니다.

---

4. 경로 포함 매개변수

경로 매개변수로 파일 경로나 디렉토리 경로와 같은 경로 자체를 받아야 하는 경우가 있습니다. 이때 FastAPI는 경로 변환기를 사용하여 경로를 포함한 데이터를 처리할 수 있습니다.

4.1 경로 포함 매개변수 선언

@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

• :path 변환기를 사용하여 file_path 매개변수가 슬래시(/)를 포함하는 경로 값을 처리할 수 있습니다.
• 예를 들어, http://127.0.0.1:8000/files/home/johndoe/myfile.txt와 같은 경로에서 file_path는 home/johndoe/myfile.txt로 전달됩니다.

4.2 OpenAPI와 경로 포함 매개변수

OpenAPI는 경로를 포함한 매개변수에 대한 명확한 지원을 제공하지 않지만, FastAPI는 Starlette의 기능을 활용하여 이를 처리할 수 있습니다. 문서에는 경로 포함 여부가 명시되지 않지만 기능적으로는 문제없이 동작합니다.

---

5. 정리 및 요약

FastAPI의 경로 매개변수는 간결하고 직관적인 방식으로 다양한 기능을 제공합니다. 주요 특징은 다음과 같습니다:

• 경로 매개변수: 요청 URL에서 데이터를 추출하여 처리. 경로에서 특정 부분을 변수로 사용하여 동적으로 데이터를 처리할 수 있음.
• 타입 어노테이션: 데이터 타입을 명시하여 자동으로 데이터 검증 및 변환. 이는 API의 신뢰성과 안정성을 높임.
• Enum을 통한 고정 값: 경로 매개변수로 허용된 값을 제한하여 더 안전한 API를 설계할 수 있음.
• 경로 포함 매개변수: 파일 경로나 디렉토리 경로와 같은 데이터를 슬래시(/) 포함한 경로로 처리할 수 있음.
• 자동 문서화: FastAPI는 경로 매개변수를 기반으로 대화형 API 문서를 자동으로 생성하고, 이를 통해 API 사용자는 쉽게 API를 이해하고 사용할 수 있음.

이러한 기능을 통해 FastAPI는 매우 직관적이고 강력한 API 프레임워크로서, 개발자는 짧은 코드로 안전하고 효율적인 API를 개발할 수 있습니다.

---