OpenAPI schema: Missing description with Query parameters

[lspgn]

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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 fastapi import FastAPI, APIRouter, Depends
import uvicorn
from typing import List
from fastapi import Query
from pydantic import BaseModel, Field
import os


class A(BaseModel):
    foo: str = Field(
        description="This is Foo",
    )


class B(A):
    bar: str = Field(
        description="This is Bar with alias",
        alias="bar2",
    )


class C(B):
    def __init__(self, xyz: str = Query(description="This is Xyz")):
        self.xyz = xyz


app = FastAPI(docs_url=None, redoc_url="/redocs")

rtr_api = APIRouter(prefix="/api")


@rtr_api.get(
    "/test1",
    description="Query me",
    summary="Querio-matic 1",
    response_model=List[B],
)
async def test(bdata: B = Depends()):
    return [bdata]


@rtr_api.get(
    "/test2",
    description="Query me 2",
    summary="Querio-matic 2",
    response_model=List[B],
)
async def test2(bdata: B):
    return [bdata]


@rtr_api.get(
    "/test3",
    description="Query me 3",
    summary="Querio-matic 3",
    response_model=List[C],
)
async def test3(bdata: C = Depends()):
    return [bdata]


app.include_router(rtr_api)

if __name__ == "__main__":
    uvicorn.run(
        app,
        port=int(os.environ.get("PORT", "8000")),
        host=os.environ.get("HOST", "localhost"),
        debug=True,
    )

Description

• I would like to use classes with Fields with description for query parameters. Example:

  class MyClass(BaseModel):
    bar: str = Field(description="This is Bar", alias="bar2")
  
  async def fct(data: MyClass = Depends()):

• The parsing works, aliases work. But the OpenAPI Schema does not show the description of the field.

To test

• Using the source code provided, go on http://localhost:8000/redocs
• Notice foo and bar2 are only described when used without Depends(). This is for a Body schema (using with refs in the OpenAPI JSON).
• The only way to have the description field is to use a Query structure as an argument in the init. The following also does not show the description.

  class MyClass(BaseModel):
    bar: str = Query(description="This is Bar", alias="bar2")
  

While this usage is not documented, I would be hoping to use Classes inheritance to define query parameters and reuse descriptions. This does not seem possible without adding it manually to the schema. Yet I was still unsure if it's an expected behavior since alias is still taken into account. The reason for using Fields would be to also re-use those schemas when returning a response.
Perhaps I am missing a Python feature that would make this possible when setting the __init__ ? If I use def __init__(self, xyz: B = Query()):, I get AssertionError: Param: xyz can only be a request body, using Body()

Thank you for your help

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.79.0

Python Version

Python 3.9.12

Additional Context

OpenAPI JSON file:
openapi-fastapi-github-issue.txt

You can see the difference between

jq '.paths["/api/test1"].get.parameters

[
  {
    "required": true,
    "schema": {
      "title": "Foo",
      "type": "string"
    },
    "name": "foo",
    "in": "query"
  },
  {
    "required": true,
    "schema": {
      "title": "Bar2",
      "type": "string"
    },
    "name": "bar2",
    "in": "query"
  }
]

jq '.paths["/api/test3"].get.parameters

[
  {
    "description": "This is Xyz",
    "required": true,
    "schema": {
      "title": "Xyz",
      "type": "string",
      "description": "This is Xyz"
    },
    "name": "xyz",
    "in": "query"
  }
]

[jujumilk3]

There's already registered relevant issue at #4700

[alexandercronin]

This appears to be not a fully supported function yet #11037 (comment)

I believe using Pydantic models for GET params is not officially supported, and whatever of it works is only the case by accident. Using nested Pydantic models to define GET params is particularly problematic; there are many mentions of this if you search the issues and discussions. See this comment by @tiangolo.

The roadmap has plans for official support:

Support for Pydantic models for Query(), Form(), etc.

#10556 (comment) #318 (comment)

With some attempted work rounds

• Query parameters from Depends do not show description in docs #4700
  • says that is you use python class, or dataclasses that it works as long as you use the Query object and not the Field object
  • mentions module to convert from pydantic classes on the fly https://github.com/dotX12/pyfa-converter
• 🔧 Keep description when endpoint depends schema #4573
  • suggests using Query(Query( appears to work Query parameters from Depends do not show description in docs #4700 (comment)
  • suggests to work with enum: Query parameters from Depends do not show description in docs #4700 (comment)

[YuriiMotov]

Since FastAPI 0.115.0 you can oficially use Pydantic models to define Query parameters.
And descriptions work fine:

from typing import List

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field


class A(BaseModel):
    foo: str = Field(description="This is Foo")

class B(A):
    bar: str = Field(
        description="This is Bar with alias",
        alias="bar2",
    )

app = FastAPI(docs_url=None, redoc_url="/redocs")

@app.get("/test1", response_model=List[B])
async def test(bdata: B = Query()):
    return [bdata]


@app.get("/test2", response_model=List[B])
async def test2(bdata: B):
    return [bdata]

[canwaf]

Thanks @YuriiMotov for this example, it took me a long time to realize that you can only pass one each of [Query(), Body()] to an endpoint with this approach and keep the OpenAPI docs metadata. I was attempting an endpoint which took separate item query parameters from pagination query parameters, and neither set of Fields would have the OpenAPI metadata show up.

I ended up solving this by mixing the inheritance of item BaseModel to include the pagination fields.

I originally thought this was a bug (it may well be), but I can also understand why the limitation exists. So I'm just adding this comment here for other people who might find your example and wonder why it's still not working for them.