Parâmetros da Rota e Validações Numéricas¶

Do mesmo modo que você pode declarar mais validações e metadados para parâmetros de consulta com Query, você pode declarar os mesmos tipos de validações e metadados para parâmetros de rota com Path.

Importe `Path`¶

Primeiro, importe Path de fastapi:

Python 3.10+Python 3.8+

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: str | None = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

from typing import Union

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: Union[str, None] = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Declare metadados¶

Você pode declarar todos os parâmetros da mesma maneira que na Query.

Por exemplo para declarar um valor de metadado title para o parâmetro de rota item_id você pode digitar:

Python 3.10+Python 3.8+

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: str | None = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

from typing import Union

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: Union[str, None] = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Nota

Um parâmetro de rota é sempre obrigatório, como se fizesse parte da rota.

Então, você deve declará-lo com ... para marcá-lo como obrigatório.

Mesmo que você declare-o como None ou defina um valor padrão, isso não teria efeito algum, o parâmetro ainda seria obrigatório.

Ordene os parâmetros de acordo com sua necessidade¶

Suponha que você queira declarar o parâmetro de consulta q como uma str obrigatória.

E você não precisa declarar mais nada em relação a este parâmetro, então você não precisa necessariamente usar Query.

Mas você ainda precisa usar Path para o parâmetro de rota item_id.

O Python irá acusar se você colocar um elemento com um valor padrão definido antes de outro que não tenha um valor padrão.

Mas você pode reordená-los, colocando primeiro o elemento sem o valor padrão (o parâmetro de consulta q).

Isso não faz diferença para o FastAPI. Ele vai detectar os parâmetros pelos seus nomes, tipos e definições padrão (Query, Path, etc), sem se importar com a ordem.

Então, você pode declarar sua função assim:

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(q: str, item_id: int = Path(title="The ID of the item to get")):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Ordene os parâmetros de a acordo com sua necessidade, truques¶

Se você quiser declarar o parâmetro de consulta q sem um Query nem um valor padrão, e o parâmetro de rota item_id usando Path, e definí-los em uma ordem diferente, Python tem um pequeno truque na sintaxe para isso.

Passe *, como o primeiro parâmetro da função.

O Python não vai fazer nada com esse *, mas ele vai saber que a partir dali os parâmetros seguintes deverão ser chamados argumentos nomeados (pares chave-valor), também conhecidos como kwargs. Mesmo que eles não possuam um valor padrão.

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(*, item_id: int = Path(title="The ID of the item to get"), q: str):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Validações numéricas: maior que ou igual¶

Com Query e Path (e outras que você verá mais tarde) você pode declarar restrições numéricas.

Aqui, com ge=1, item_id precisará ser um número inteiro maior que ("greater than") ou igual ("equal") a 1.

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *, item_id: int = Path(title="The ID of the item to get", ge=1), q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Validações numéricas: maior que e menor que ou igual¶

O mesmo se aplica para:

gt: maior que (greater than)
le: menor que ou igual (less than or equal)

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(title="The ID of the item to get", gt=0, le=1000),
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Validações numéricas: valores do tipo float, maior que e menor que¶

Validações numéricas também funcionam para valores do tipo float.

Aqui é onde se torna importante a possibilidade de declarar gt e não apenas ge. Com isso você pode especificar, por exemplo, que um valor deve ser maior que 0, ainda que seja menor que 1.

Assim, 0.5 seria um valor válido. Mas 0.0 ou 0 não seria.

E o mesmo para lt.

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(title="The ID of the item to get", ge=0, le=1000),
    q: str,
    size: float = Query(gt=0, lt=10.5),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Recapitulando¶

Com Query, Path (e outras que você ainda não viu) você pode declarar metadados e validações de texto do mesmo modo que com Parâmetros de consulta e validações de texto.

E você também pode declarar validações numéricas:

gt: maior que (greater than)
ge: maior que ou igual (greater than or equal)
lt: menor que (less than)
le: menor que ou igual (less than or equal)

Informação

Query, Path e outras classes que você verá a frente são subclasses de uma classe comum Param.

Todas elas compartilham os mesmos parâmetros para validação adicional e metadados que você viu.

Detalhes Técnicos

Quando você importa Query, Path e outras de fastapi, elas são na verdade funções.

Que quando chamadas, retornam instâncias de classes de mesmo nome.

Então, você importa Query, que é uma função. E quando você a chama, ela retorna uma instância de uma classe também chamada Query.

Estas funções são assim (ao invés de apenas usar as classes diretamente) para que seu editor não acuse erros sobre seus tipos.

Dessa maneira você pode user seu editor e ferramentas de desenvolvimento sem precisar adicionar configurações customizadas para ignorar estes erros.