[Bug] Using Annotated[Optional[str], Query(alias="q")] = None prevents type from being shown for parameter in Swagger UI

[caffeinatedMike]

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 typing import Annotated, Optional

import uvicorn
from fastapi import APIRouter, FastAPI, Query

api = APIRouter(prefix="/api")

@api.get("/a")
async def a(
    x: Annotated[str, Query()] = None,
    y: Annotated[int, Query()] = None,
    z: Annotated[bool, Query()] = False
):
    """Properly shows parameter types in Swagger UI, but MyPy complains."""

@api.get("/b")
async def b(
    x: Annotated[Optional[str], Query()] = None,
    y: Annotated[Optional[int], Query()] = None,
    z: Annotated[Optional[bool], Query()] = False
):
    """Satisfies MyPy, but fails to show parameter types in Swagger UI."""


app = FastAPI(docs_url="/")
app.include_router(api)

if __name__ == "__main__":
    uvicorn.run("__main__:app", host="0.0.0.0", port=8000)

Description

• Open the browser and call the endpoint /
• In the Swagger UI you will see the following:
  1. x, y, and z query parameters under the route /api/a show their related types
     • This shows that Annotated[...] works properly with FastAPI and displays the appropriate types
  2. x, y, and z query parameters under the route /api/b do not show their related types
     • This shows that Annotated[Optional[...]] does not work properly with FastAPI because it does not display the parameters' respective types.
• What's expected?
  • FastAPI should properly handle types wrapped with Optional[...] inside Annotated[...], which is the new way that is encouraged throughout the FastAPI docs for specifying parameter types and additional details.

Operating System

Windows

Operating System Details

No response

FastAPI Version

0.109.2

Pydantic Version

2.6.1

Python Version

Python 3.9.13

Additional Context

New way with Annotated, without Optional - Working

New way with Annotated, with Optional - Not Working

[JavierSanchezCastro]

Try this #10836 (reply in thread)

[caffeinatedMike]

That is a holdover solution, thank you! I expected that solution to still not satisfy mypy --strict, but somehow it does even without the parameter types wrapped in Optional[...]? 😕

@api.get("/c")
async def c(
    x: Annotated[Union[str, SkipJsonSchema[None]], Query()] = None,
    y: Annotated[Union[int, SkipJsonSchema[None]], Query()] = None,
    z: Annotated[Union[bool, SkipJsonSchema[None]], Query()] = False
):
    """Temporary fix.

    [Pydantic: Add SkipJsonSchema annotation #6653](https://github.com/pydantic/pydantic/pull/6653)

    Waiting on
    [FastAPI: Add custom GenerateJsonSchema #9873](https://github.com/tiangolo/fastapi/pull/9873)
    """

[caffeinatedMike]

Furthermore, I found that this solution provided by dmontagu helps in packaging the logic into a custom type factory to utilize this fix.

import json
from typing import TYPE_CHECKING, Annotated, Union

from pydantic import BaseModel, Field
from pydantic.json_schema import SkipJsonSchema

if TYPE_CHECKING:
    from typing import Optional as OptionalParam
else:
    class OptionalParam:
        def __class_getitem__(cls, item):
            return Annotated[
                Union[item, SkipJsonSchema[None]],
                Field(json_schema_extra=lambda x: x.pop('default', None))
            ]