Parameters API Reference¶

Complete reference for all parameter classes in FastOpenAPI.

Query¶

Extract and validate query parameters from the URL query string.

from fastopenapi import Query

Signature¶

Query(
    default: Any = None,
    *,
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    strict: bool | None = None,
    multiple_of: float | None = None,
    allow_inf_nan: bool | None = None,
    max_digits: int | None = None,
    decimal_places: int | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
)

Parameters¶

default: Default value if not provided (default: None)
alias: Alternative name in the query string
title: Title for OpenAPI documentation
description: Description for OpenAPI documentation
gt: Greater than validation (numbers)
ge: Greater than or equal validation (numbers)
lt: Less than validation (numbers)
le: Less than or equal validation (numbers)
min_length: Minimum length (strings/arrays)
max_length: Maximum length (strings/arrays)
pattern: Regular expression pattern (strings)
strict: Enable strict type checking
multiple_of: Number must be a multiple of this value
allow_inf_nan: Allow infinity and NaN values
max_digits: Maximum number of digits
decimal_places: Maximum decimal places
examples: Example values for documentation
deprecated: Mark as deprecated in docs
include_in_schema: Include in OpenAPI schema
json_schema_extra: Extra JSON schema properties

Example¶

@router.get("/items")
def list_items(
    page: int = Query(1, ge=1, description="Page number"),
    per_page: int = Query(10, ge=1, le=100, description="Items per page"),
    search: str | None = Query(None, description="Search query"),
):
    return {"page": page, "per_page": per_page}

Path¶

Extract and validate path parameters from the URL path.

from fastopenapi import Path

Signature¶

Path(
    default: Any = ...,  # Always required (...)
    *,
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    strict: bool | None = None,
    multiple_of: float | None = None,
    allow_inf_nan: bool | None = None,
    max_digits: int | None = None,
    decimal_places: int | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
)

Parameters¶

Same as Query, except:

default: Must be ... (ellipsis) - path parameters are always required

Important¶

Path parameters cannot have default values. Attempting to provide a default value other than ... will raise a ValueError.

Example¶

@router.get("/users/{user_id}/posts/{post_id}")
def get_post(
    user_id: int = Path(..., ge=1, description="User ID"),
    post_id: int = Path(..., ge=1, description="Post ID"),
):
    return {"user_id": user_id, "post_id": post_id}

Extract and validate HTTP header values.

from fastopenapi import Header

Signature¶

Header(
    default: Any = None,
    *,
    alias: str | None = None,
    convert_underscores: bool = True,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    strict: bool | None = None,
    multiple_of: float | None = None,
    allow_inf_nan: bool | None = None,
    max_digits: int | None = None,
    decimal_places: int | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
)

Parameters¶

Same as Query, plus:

convert_underscores: Automatically convert underscores to hyphens (default: True)

Example¶

@router.get("/items")
def list_items(
    user_agent: str | None = Header(None, alias="User-Agent"),
    api_key: str = Header(..., alias="X-API-Key", description="API Key"),
):
    return {"user_agent": user_agent}

Note: HTTP headers are case-insensitive but typically use kebab-case (e.g., User-Agent, X-API-Key).

Extract and validate HTTP cookie values.

from fastopenapi import Cookie

Signature¶

Cookie(
    default: Any = None,
    *,
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    strict: bool | None = None,
    multiple_of: float | None = None,
    allow_inf_nan: bool | None = None,
    max_digits: int | None = None,
    decimal_places: int | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
)

Parameters¶

Same as Query.

Example¶

@router.get("/profile")
def get_profile(
    session_id: str = Cookie(..., description="Session ID"),
    preferences: str | None = Cookie(None),
):
    return {"session_id": session_id}

Body¶

Extract and validate JSON request body.

from fastopenapi import Body

Signature¶

Body(
    default: Any = None,
    *,
    media_type: str = "application/json",
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    strict: bool | None = None,
    multiple_of: float | None = None,
    allow_inf_nan: bool | None = None,
    max_digits: int | None = None,
    decimal_places: int | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
)

Parameters¶

Same as Query, plus:

media_type: MIME type of the body (default: "application/json")

Example¶

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

@router.post("/items")
def create_item(item: Item = Body(...)):
    return item

Form¶

Extract and validate form data from application/x-www-form-urlencoded requests.

from fastopenapi import Form

Signature¶

Form(
    default: Any = None,
    *,
    media_type: str = "application/x-www-form-urlencoded",
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    strict: bool | None = None,
    multiple_of: float | None = None,
    allow_inf_nan: bool | None = None,
    max_digits: int | None = None,
    decimal_places: int | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
)

Parameters¶

Same as Body.

Example¶

@router.post("/login")
def login(
    username: str = Form(...),
    password: str = Form(...),
):
    return {"username": username}

File¶

Handle file uploads from multipart/form-data requests.

from fastopenapi import File

Signature¶

File(
    default: Any = None,
    *,
    media_type: str = "multipart/form-data",
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
)

Parameters¶

Same as Form (inherits from Form, validation constraints don't apply to files).

Example¶

from fastopenapi import File, FileUpload

@router.post("/upload")
def upload_file(file: FileUpload = File(...)):
    content = file.read()  # Sync frameworks
    return {
        "filename": file.filename,
        "content_type": file.content_type,
        "size": file.size
    }

@router.post("/upload-async")
async def upload_file_async(file: FileUpload = File(...)):
    content = await file.aread()  # Async frameworks
    return {"filename": file.filename}

Validation Constraints¶

All parameter classes support Pydantic validation constraints:

Numeric Constraints¶

gt: Greater than
ge: Greater than or equal
lt: Less than
le: Less than or equal
multiple_of: Must be a multiple of this value

age: int = Query(..., ge=0, le=150)
price: float = Query(..., gt=0, le=1000000)
quantity: int = Query(..., multiple_of=10)

String Constraints¶

min_length: Minimum string length
max_length: Maximum string length
pattern: Regular expression pattern

username: str = Query(..., min_length=3, max_length=50)
email: str = Query(..., pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')

Number Constraints¶

max_digits: Maximum total digits
decimal_places: Maximum decimal places
allow_inf_nan: Allow infinity and NaN

price: float = Query(..., max_digits=10, decimal_places=2)

Metadata¶

All parameters support OpenAPI metadata:

@router.get("/items")
def list_items(
    search: str = Query(
        None,
        title="Search Query",
        description="Search items by name or description",
        examples=["laptop", "phone"],
        deprecated=False,
        alias="q"
    )
):
    return {}

title: Short title for the parameter
description: Longer description
examples: Example values (shown in OpenAPI docs)
deprecated: Mark parameter as deprecated
alias: Alternative parameter name
include_in_schema: Include in OpenAPI schema (default: True)
json_schema_extra: Additional JSON schema properties

Parameters API Reference¶

Query¶

Signature¶

Parameters¶

Example¶

Path¶

Signature¶

Parameters¶

Important¶

Example¶

Header¶

Signature¶

Parameters¶

Example¶

Signature¶

Parameters¶

Example¶

Body¶

Signature¶

Parameters¶

Example¶

Form¶

Signature¶

Parameters¶

Example¶

File¶

Signature¶

Parameters¶

Example¶

Validation Constraints¶

Numeric Constraints¶

String Constraints¶

Number Constraints¶

Metadata¶

See Also¶

Parameters API Reference¶

Query¶

Signature¶

Parameters¶

Example¶

Path¶

Signature¶

Parameters¶

Important¶

Example¶

Header¶

Signature¶

Parameters¶

Example¶

Cookie¶

Signature¶

Parameters¶

Example¶

Body¶

Signature¶

Parameters¶

Example¶

Form¶

Signature¶

Parameters¶

Example¶

File¶

Signature¶

Parameters¶

Example¶

Validation Constraints¶

Numeric Constraints¶

String Constraints¶

Number Constraints¶

Metadata¶

See Also¶