FastAPI 공식문서 따라하기[6] - Query Parameters and String Validations

https://fastapi.tiangolo.com/ko/ 공식문서 따라하는 글

☑️ 1. Query Parameters and String Validations

FastAPI는 파라미터에 유효성 검사나 추가적인 정보를 추가할 수 있다.

from typing import Optional

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(q: Optional[str] = None) :
    results = {"items": [{"item_id" : "kms"}, {"item_id" : "jyb"}]}
    if q:
        results.update({"q":q})
    return results

query parameter인 q는 Optional[str] = None을 주어서 q의 타입은 str이거나 None으로 지정할 수 있게 하였다. 값이 없을경우 None이 되고 FastAPI는 이 값이 필수값이 아닌것을 알 수 있게 된다.

---

☑️ 2. Additional validation

• 글자수를 제한 할 수 있다.

먼저 Query를 Import해야 한다.

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: Optional[str] = Query(None, max_length=50)) :
    results = {"items" : [{"item_id": "kms"},{"item_id" : "jyb"}]}
    if q :
        results.update({"q" : q})
    return results

50자를 넘겼을 경우

• Query의 첫 번째 파라미터인 Query(None)을 통하여 default value를 지정해줄 수 있다.

즉

q: Optional[str] = Query(None) 와
q: Optional[str] = None은 같은 기능을 수행합니다.

• Query의 두 번째 파라미터인 max_length는 문자열에 적용된다. 만약 문자열이 아니라면 오류를 냅니다.

☑️ 3. Add reuglar expressions

• 파라미터에 정규 표현식을 사용할 수 있다.

from typing import Optional

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Optional[str] = Query(None,min_length=3,max_length=50, regex="^fixedquery$")
):
    results = {"items" : [{"item_id" : "Kms"}, {"item_id" : "Bar"}]}
    if q:
        results.update({"q" : q})
    return results

정규표현식^와 $에 의하여 query parameter는 fixedquery라는 고정된 값이 들어오거나 None이어야한다.

• ^ : 무조건 ^다음에 단어로 시작해야한다. ^앞에 단어가 있으면 안 된다.
• $ : 문자열의 끝을 알리기에, $다음에 문자가 나오면 안된다.

즉 들어와야할 q는 fixedquery라는 문자열만 가능하다는 것이다.

문서에서는 정규표현식을 몰라도 되고, 혹여 나중에 공부를 한다면 FastAPI에서는 이미 정규표현식을 지원을하고 있음을 알리고 있다.

---

☑️ 4. Default values

여태까지는 None으로 Default값을 설정하였지만, 다른 값으로도 설정이 가능하다는 것이다.

query parameter로 들어오는 값은 최소 3글자 이상이어야하고, 값이 들어오지 않는다면 MyProjectIsDia로 바꿔보겠다.

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query("MyProjectIsDia",min_length=3)) :
    results = {"items" : [{"item_id": "Kms"}, {"item_id": "Test"}]}
    if q:
        results.update({"q" : q})
    return results

Default value:MyProjectIsDia로 지정되어 있는걸 확인할 수 있다.

---

☑️ 5. Make it required

• Query Parameter를 필수값으로 받게 할 수 있다.

물론 q: str을 통해 필수값으로 바꿀 수 있었지만, Query를 통해서 바꾸려면 어떻게 해야할까? 그것은 바로 첫 파라미터에 ...을 넣으면 된다.

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str = Query(...,min_length=3)) :
    results = {"items" : [{"item_id": "Kms"}, {"item_id": "Test"}]}
    if q:
        results.update({"q" : q})
    return results

requried가 붙고 minLength:3도 붙은걸 볼 수 있다.

---

☑️ 6. Query parameter list/ multiple values

• list도 Query Parameter로 지원합니다.

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: list[str] | None = Query(None)):
    query_items = {"q": q}
    return query_items

http://127.0.0.1:8000/items/?q=test&q=kms

이렇게 테스트할 수 있다.

결과

{"q":["test","kms"]}

만약 list타입으로 QueryParameter를 선언하면 python 코드에서는 Query를 명시적으로 달아줘야합니다. 그러지 않으면 FastAPI requestbody로 해석합니다.

List의 Default값을 설정하려면?

async def read_items(q: list[str] = Query(["test","kms"])):

이렇게 해주면 된다.

결과

http://127.0.0.1:8000/items/

{"q":["test","kms"]}

async def read_items(q:list = Query([])):

이렇게 선언도 가능하다. 하지만 자료형을 명시해주지 않았다.

확인해보니 str형으로 받긴 하는데

---

☑️ 7. Declare more metadata

• 추가적으로 쿼리파라미터를 조작할 수 있다

title과 description사용 예제

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str
    | None = Query(
        None,
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

공식문서에서는 다음과 같이 얘기한다.

• title : 사용 API의 이름
• description : 사용 API의 설명

☑️ 8. Alias parameters

만약 item-query를 parameter로 받고 싶은 경우가 있을 수 있다.

하지만 python에서는 -이 포함된 변수이름을 지원하지 않고 item_query로 대체해야한다.

그래도 item-query로 사용하고 싶다면 alias를 사용하면 된다.

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(q: str | None = Query(None, alias="item-query")):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

또한 deprecated=True와 같은 값을 파라미터로 넘겨주면, OpenAPI docs에서 deprecated를 명시해줄 수 있다.

요청을 보내면 가므로 docs관리용

---

☑️ 9. Exclude from OpenAPI

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(hidden_query: str | None = Query(None, include_in_schema=False)):
    if hidden_query:
        return {"hidden_query": hidden_query}
    else:
        return {"hidden_query": "Not found"}

이렇게 include_in_schema=False옵션을 주면 OpenAPI docs에서 해당 파라미터를 제외할 수 있다.

docs에서만 제외되므로 실제 요청은 간다.

http://localhost:8000/items/?hidden_query=hi

결과