Scalable approach to defining query parameters

[lcdunne]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from dataclasses import dataclass
from enum import Enum
from typing import Annotated

from fastapi import APIRouter, Depends, FastAPI, Query
from pydantic import BaseModel, Field
from pydantic.dataclasses import dataclass as pdataclass

app = FastAPI()
router = APIRouter(prefix="/api")


class Animal(str, Enum):
    CAT = "CAT"
    DOG = "DOG"


class CommonQueryParams1(BaseModel):
    # Types working
    # Descriptions NOT working
    # Example working
    q: str | None = Query(
        default=None, description="Some string query param.", example="fooooo"
    )
    animal: Animal = Query(default=Animal.CAT, description="The animal.")

    skip: int = Query(default=0, description="Skips results.")
    limit: int = Query(default=50, ge=1, le=100, description="Show this many.")


class CommonQueryParams2(BaseModel):
    # Types working
    # Descriptions working
    # Example working
    q: str | None = Field(
        Query(default=None, description="Some string query param.", example="fooooo")
    )
    animal: Animal = Field(Query(default=Animal.CAT, description="The animal."))
    skip: int = Field(Query(default=0, description="Skips results."))
    limit: int = Field(Query(default=50, ge=1, le=100, description="Show this many."))


class CommonQueryParams3:
    # Types working
    # Descriptions working
    # Example working
    def __init__(
        self,
        q: str = Query(
            default=None, description="Some string query param.", example="fooooo"
        ),
        animal: Animal = Query(default=Animal.CAT, description="The animal."),
        skip: int = Query(default=0, description="Skips results."),
        limit: int = Query(default=50, ge=1, le=100, description="Show this many."),
    ):
        self.q = q
        self.animal = animal
        self.skip = skip
        self.limit = limit


@dataclass
class CommonQueryParams4:
    # Types working
    # Descriptions working
    # Example working
    q: str | None = Query(
        default=None,
        description="Some string query param.",
        example="fooooo",
    )
    animal: Animal = Query(
        default=Animal.CAT,
        # enum=Animal,
        description="The animal.",
    )
    skip: int = Query(default=0, description="Skips results.")
    limit: int = Query(default=50, ge=1, le=100, description="Show this many.")


@pdataclass
class CommonQueryParams5:
    # Types working
    # Descriptions NOT working
    # Example working
    q: str | None = Query(
        default=None,
        description="Some string query param.",
        examples=["foo", "bar", "baz"],
        example="fooooo",
    )
    animal: Animal = Query(
        default=Animal.CAT,
        # enum=Animal,
        description="The animal.",
    )
    skip: int = Query(default=0, description="Skips results.")
    limit: int = Query(default=50, ge=1, le=100, description="Show this many.")


class CommonQueryParams6(BaseModel):
    # Types working
    # Descriptions NOT working
    # Example working
    q: str | None = Field(
        default=None,
        description="Some string query param.",
        examples=["fooooo"],
    )
    animal: Animal = Field(
        default=Animal.CAT,
        description="The animal.",
    )

    skip: int = Field(default=0, description="Skips results.")
    limit: int = Field(default=50, ge=1, le=100, description="Show this many.")


@router.get("/widgets")
def get_widgets(q: CommonQueryParams1 = Depends()):
    print(q, type(q))
    return {"data": "got widgets"}


@router.get("/widgets2")
def get_widgets2(q: CommonQueryParams2 = Depends()):
    print(q, type(q))
    return {"data": "got widgets"}


@router.get("/widgets3")
def get_widgets3(q: CommonQueryParams3 = Depends()):
    print(q, type(q))
    return {"data": "got widgets"}


@router.get("/widgets4")
def get_widgets4(q: CommonQueryParams4 = Depends()):
    print(q, type(q))
    return {"data": "got widgets"}


@router.get("/widgets5")
def get_widgets5(q: CommonQueryParams5 = Depends()):
    print(q, type(q))
    return {"data": "got widgets"}


@router.get("/widgets6")
def get_widgets6(q: CommonQueryParams6 = Depends()):
    print(q, type(q))
    return {"data": "got widgets"}


@router.get("/widgets7")
def get_widgets7(q: Annotated[CommonQueryParams2, Depends()]):
    print(q, type(q))
    return {"data": "got widgets"}


app.include_router(router)

Description

I think there is a lack of clarity in how to define query parameters in a way that is scalable and that works. Some approaches appear to work, but actually fail to show the parameters' descriptions in the swagger. I was expecting that I would simply be able to define my query params as I did in CommonQueryParams1, using pydantic's BaseModel, but this fails to show the descriptions. I would find this approach preferable if it were supported.

As you can see from my main example code, we currently can:

• Scatter query params in the route function signature (not scalable and would lead to repeated code)
• Define them as vanilla python classes (e.g. Classes as Dependencies, but that's inconsistent with the use of Pydantic base models for reqs/resps)
• Define them as a dataclass (again inconsistent; for example this thread)
• Define them as a pydantic BaseModel where we wrap the Query fields with Field (feels like a hack; see last thread linked in point)

The mentioned thread ends without a conclusion, and the contributions are from a few years ago now. And there is not a clear recommendation from the docs but it would be helpful if we could get some clarity on it.

Currently I am leaning towards using either the dataclass approach or the vanilla python class approach. It also works with a pydantic basemodel as long as we wrap the query objects in pydantic's Field, but I think it seems like more of a workaround and I am not sure how compatible this will be?

For reference, my installed libs are:

annotated-types==0.6.0
anyio==4.3.0
click==8.1.7
colorama==0.4.6
fastapi==0.110.2
h11==0.14.0
idna==3.7
pydantic==2.7.1
pydantic_core==2.18.2
sniffio==1.3.1
starlette==0.37.2
typing_extensions==4.11.0
uvicorn==0.22.0

Apologies if this isn't actually a FastAPI issue, although it feels like it might be.

Operating System

Windows

Operating System Details

I've tried this on Mac too, but it is not anything to do with the OS.

FastAPI Version

0.110.2

Pydantic Version

2.7.1

Python Version

3.12.4

Additional Context

Have tried this with other versions of python and also the latest fastapi and it seems to still be problematic.

[YuriiMotov]

Don't use Pydantic models for non-body parameters (Query, Form, Path, ...), it's not officially supported by FastAPI.
Take a look at the answer of Sebastián Ramírez to this comment: #9709 (comment), also #9709 (comment)

[lcdunne]

Thanks for pointing this out. Can you see any problems with using e.g. a standard dataclass for this?

[YuriiMotov]

As I know it's said nothing about using dataclasses as parameters in FastAPI endpoints. So, it's also on your risk. But in some simple use cases it works