FastAPI 배우기 - Path Parameters

공식문서를 번역한 내용입니다

https://fastapi.tiangolo.com/ko/tutorial/path-params/

경로 매개변수 - FastAPI

---

경로 매개변수

from fastapi import FastAPI

app = FastAPI()

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

경로 매개변수 item_id의 값은 함수의 item_id 인자로 전달

이 예제를 실행 후 http://127.0.0.1:8000/items/foo로 이동하면, 다음 응답을 볼 수 있다:

{”item_id”:”foo”}

타입이 있는 매개변수

파이썬 표준 타입 어노테이션을 사용하여 함수에 있는 경로 매개변수의 타입을 선언할 수 있다

from fastapi import FastAPI

app = FastAPI()

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

item_id는 int로 선언됨

데이터 변환

위의 예제에서 http://127.0.0.1:8000/items/3을 열면, 다음 응답을 볼 수 있다:

{"item_id":3}

데이터 검증

하지만 http://127.0.0.1:8000/items/foo로 이동하면, HTTP 오류를 볼 수 있다:

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

경로 매개변수 item_id는 int가 아닌 “foo”값이기 떄문이다.

int 대신 float을 전달하면 동일한 오류가 나타난다.

문서화

브라우저에서 http://127.0.0.1:8000/docs를 열면, 자동 대화식 API 문서를 볼 수 있다.

대체 문서화

생성된 스키마는 OpenAPI 표준에서 나온 것이기 때문에 호환되는 도구가 많다

이 덕분에 FastAPI는 http://127.0.0.1:8000/redoc로 접속할 수 있는(Redoc을 사용하는) 대체 API 문서를 제공한다.

Pydantic

모든 데이터 검증은 Pydantic에서 내부적으로 수행함.

str, float, bool과 다른 복잡한 데이터 타입 선언을 할 수 있다.

순서 문제

예제를 들면

/users/me와 /users/{user_id} 2가지 경로를 만들었다고 했을때.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}

@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

경로 동작은 순차적으로 평가되기 때문에 /users/me를 먼저 선언한다.

그렇지 않다면 /users/{user_id}는 매개변수 user_id의 값을 me라고 생각하여 /users/me도 연결한다.

사전정의 값

• Enum을 import하고 str과 Enum을 상속하는 서브 클래스 생성
• str에서 상속함으로써 API문서는 값이 string 유형이어야 하고 올바르게 렌더링 할 수 있음을 알 수 있다.

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 == ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}
		#열거형 값 가져오기
    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}
		#열거형 멤버 반환
    return {"model_name": model_name, "message": "Have some residuals"}

경로 매개변수 선언

생성한 Enum 클래스(ModelName)를 사용하여 자료형 어노테이션이 있는 경로 매개변수를 생성합니다.

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 == ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}
		#열거형 값 가져오기
    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}
		#열거형 멤버 반환
    return {"model_name": model_name, "message": "Have some residuals"}

문서확인

경로 매개변수에 사용할 수 있는 값은 미리 정의 되어 있으므로 http://127.0.0.1:8000/docs에서 확인 가능하다.

파이썬 열거형으로 작업하기

경로 매개변수의 값은 열거형 멤버가 된다

열거형 멤버 비교

ModelName이라는 이름으로 만든 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 == ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

열거형 값 가져오기

model_name.value 또는 일반적으로 your_enum_member.value를 이용하여 실제값(지금의 경우 str)을 가져올 수 이다.

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 == ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

열거형 멤버 반환

(dict과 같은) 중첩된 JSON 바디나, 경로 동작으로 부터 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 == ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}

    return {"model_name": model_name, "message": "Have some residuals"}

클라이언트에서 다음과 같은 JSON 응답을 받는다.

{
  "model_name": "alexnet",
  "message": "Deep Learning FTW!"
}

경로를 포함하는 경로 매개변수

/files/{file_path}라는 경로를 가진 경로 동작이 있다고 가정해보자.

그런데 home/johndoe/myfile.txt처럼 스스로 경로를 포함하고 있는 file_path가 필요하다.

이때, 해당 파일의 URL은 다음과 같다: /files/home/johndoe/myfile.txt

OpenAPI 지원 / 경로변환

OpenAPI는 경로를 포함하는 경로 매개변수를 내부에 선언하는 방법을 지원하지 않는다.

그럼에도 Starlette에서 제공하는 옵션을 사용하면 path를 포함하는 경로매개변수를 선언 할 수 있다.

/files/{file_path:path}

이 경우 매개변수의 이름은 file_path이고 마지막 부분 :path는 매개변수가 경로와 일치해야함을 알려준다.

from fastapi import FastAPI

app = FastAPI()

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

요약

FastAPI를 이용하면, 짧고, 직관적이며, 표준 파이썬 타입 선언을 사용하여 다음을 얻을 수 있다.

• 편집기 지원: 오류검사, 자동완성 등
• 데이터 파싱(parsing)
• 데이터 검증
• API 주석(Annotation)과 자동문서