[FastAPI] 쿼리 매개변수 | study book

쿼리 매개변수

api 요청 시 특정 인덱스에서 아이템을 불러오는 때 등 특정 매개변수가 필요한 경우가 있다. Path 클래스는 FastAPI에서 경로 매개변수를 선언할 때 사용되는 특별한 클래스다. 주로 경로 매개변수의 유효성 검사, 기본값 설정, 제한 조건 등을 정의하는 데 사용된다.

 

Path 클래스는 경로 매개변수를 선언할 때 기본값을 설정하거나, 필수 매개변수로 지정할 수 있다. 경로 매개변수는 URL 경로의 일부로 전달되는 값이다.

Path() 사용법

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., description="The ID of the item to retrieve")):
    return {"item_id": item_id}

위 예시에서 item_id는 경로 매개변수로 선언되어 있으며, Path 클래스를 통해 이 매개변수에 대한 설명이 추가되었다. ...는 필수 매개변수임을 나타낸다.

 

유효성 검증

Path 클래스를 사용하여 매개변수의 유효성 검사를 쉽게 정의할 수 있다. 예를 들어, 최소값, 최대값, 정규 표현식 등을 사용하여 입력값을 제한할 수 있다.

@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., title="Item ID", ge=1)):
    return {"item_id": item_id}

ge=1은 item_id가 1 이상의 값이어야 함을 의미한다. 이렇게 하여 유효하지 않은 값이 입력되지 않도록 제한할 수 있다.

경로 기본값 설정

경로 매개변수에 기본값을 설정할 수 있다. 기본값이 설정된 매개변수는 선택적(optional)로 간주되며, URL 경로에 해당 값이 주어지지 않으면 기본값이 사용된다.

@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(1, title="Item ID")):
    return {"item_id": item_id}

위 예시에서 item_id의 기본값은 1로 설정되었다.

메타데이터

Path 클래스를 사용하여 매개변수에 메타데이터를 추가할 수 있다. 예를 들어, title, description, example 등을 지정하여 OpenAPI 문서에 표시되는 내용을 제어할 수 있다. (Redoc, Swagger 등)

@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., title="Item ID", description="The ID of the item to retrieve", example=42)):
    return {"item_id": item_id}

이렇게 하면 API 문서에서 item_id 매개변수에 대한 정보가 보다 명확하게 표시된다.

API 문서

fast api 에서는 정의된 라우팅 모델에 대해서 문서화하여 보다 간편하게 볼 수 있다. 다음은 대표적으로 사용되는 두 가지 문서이다.

1. Swagger

Swagger는 API의 정의, 문서화, 테스트, 시뮬레이션 등을 지원하는 도구 모음이다. 주로 API를 설명하는 표준화된 형식인 OpenAPI Specification(OAS)을 기반으로 한다. FastAPI는 기본적으로 Swagger UI를 통합하여 API 문서를 자동으로 생성하고 표시할 수 있다.

FastAPI에서 Swagger UI 사용 예시

# FastAPI를 실행하고 나서 브라우저에서 http://127.0.0.1:8000/docs 로 접근

2. Redoc

Redoc은 또 다른 OpenAPI 기반의 API 문서화 도구다.

FastAPI에서 Redoc 사용 예시

# FastAPI를 실행하고 나서 브라우저에서 http://127.0.0.1:8000/redoc 로 접근

Extra json Schema Data

fast api 의 api 문서에는 위의 사진처럼 요청 body를 어떻게 해주는 지 예제를 담을 수 있다. 바로 모델에 model_config 변수를 초기화해주면 되는데 책의 내용이 달라서 제대로 표시가 되질 않았다. 하지만 이것은 버전에 따른 문법차이 때문이었다. 아래의 공식문서에서 버전별 어떻게 사용하는 지 나오니 참고바란다.

https://fastapi.tiangolo.com/tutorial/schema-extra-example/

Declare Request Example Data - FastAPI

class Todo(BaseModel):
    id: int
    item: str

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "id": 1,
                    "item": "Example Schema!"
                }
            ]
        }
    }

class TodoItem(BaseModel):
    item: str

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "item": "Read the next chapter of the book"
                }
            ]
        }
    }

모델의 model_config에 json_schema_extra 값에 examples 값을 설정해주면된다. 그리고 아래와 같이 라우터 어노테이션의 메소드 아규먼트로 respones_model=dict으로 설정해준다.

# 라우터의 인자에 response_model
@todo_router.get("/todo/{todo_id}", response_model=dict)

참고 자료

https://product.kyobobook.co.kr/detail/S000201188332

FastAPI를 사용한 파이썬 웹 개발 | 압둘라지즈 압둘라지즈 아데시나 - 교보문고