使用 Pydantic model (FastAPI) 在 swagger 文档中设置查询参数的描述

Question

This is continue to this question .

I have added a model to get query params to pydantic model

class QueryParams(BaseModel):
    x: str = Field(description="query x")
    y: str = Field(description="query y")
    z: str = Field(description="query z")


@app.get("/test-query-url/{test_id}")
async def get_by_query(test_id: int, query_params: QueryParams = Depends()):
    print(test_id)
    print(query_params.dict(by_alias=True))
    return True

it is working as expected but description(added in model) is not reflecting in swagger ui

But if same model is used for request body, then description is shown in swagger

Am I missing anything to get the description for QueryParams(model) in swagger ui?

Answer 1

This is not possible with Pydantic models

The workaround to get the desired result is to have a custom dependency class (or function) rather than the Pydantic model

from fastapi import Depends, FastAPI, Query

app = FastAPI()





@app.get("/test-query/")
async def get_by_query():
    return params

Thus, you will have the doc as,

---

References

1. Validate GET parameters in FastAPI--(FastAPI GitHub) It seems like there is less interest in extending the Pydantic model to validate the GET parameters
2. Classes as Dependencies--(FastAPI Doc)

Answer 2

The accepted answer refers to the use of custom dependencies using FastAPI classes as dependencies to define the query parameters in bulk and while I think it works great, I feel the using dataclasses would be better in this case and reduces the code duplication as the __init__ will be generated automatically.

Normal class as dependency

class QueryParams:
    def __init__(self, 
    x:  Query(
            None, description="Arg1", example=10),
    y:  Query(
            None, description="Arg2", example=20)
    ):
        self.x = x
        self.y = y

While for lesser number of query params it would be just fine to do it this way but if the number of args is large as it was for me for one of my api endpoints, this quickly becomes cumbersome.

Using dataclass as a dependency

@dataclass
class QueryParams:
    x:  Query(None, description="Arg1", example=10)
    y:  Query(None, description="Arg2", example=20)

Plus you will also have added goodies of dataclasses if you need more complex functioanlities.

Answer 3

This worked for me

from fastapi import Depends, FastAPI, Query

@app.post("/route")
def some_api(
        self,
        query_param_1: float = Query(None, description="description goes here", ),
        query_param_2: float = Query(None, description="Param 2 does xyz"),
):
    
return "hello world"