Set description for query parameter in swagger doc using Pydantic model (FastAPI)

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?

I disagree with Arakkabal's answer, i was able to this, also OpenAPI Spec & Swagger allows this and query parameters has a description field [see](https://swagger.io/docs/specification/describing-parameters/#query-parameters).So that means you should be doing this, because FastAPI is based on OpenAPI specification. I'll take a look at this again, later today. — Yagiz Degirmenci, Oct 15 '20 at 07:53

JPG · Accepted Answer · 2020-10-15T07:13:32.297

17

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()


class CustomQueryParams:
    def __init__(
        self,
        foo: str = Query(..., description="Cool Description for foo"),
        bar: str = Query(..., description="Cool Description for bar"),
    ):
        self.foo = foo
        self.bar = bar


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

Thus, you will have the doc as,

References

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

edited Oct 15 '20 at 07:13

answered Oct 15 '20 at 07:04

JPG

82,442
19
127
206

1

This would do. But wanted to have pydantic model – karsas Oct 15 '20 at 07:11
You can't do this with Pydantic. [ref this](https://github.com/tiangolo/fastapi/issues/318) – JPG Oct 15 '20 at 07:14
not sure why to use Query though, it has similar attributes as pydantic Field – karsas Oct 15 '20 at 08:01
`Query(...)` is used to generate the OpenAPI schema – JPG Oct 15 '20 at 08:05

score 11 · Answer 2 · answered Oct 27 '21 at 14:13

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"

score 3 · Answer 3 · answered Apr 22 '22 at 07:52

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.

Jacob Petterle · Answer 4 · 2023-08-24T17:17:02.807

Here's a simple working example on how combine Pydantic with FastAPI for query params:

from enum import Enum
from typing import List
from fastapi import APIRouter, Depends, Query
from pydantic import BaseModel, Field

ROUTER = APIRouter()

class MyEnum(str, Enum):
    OPTION_ONE = "option_one"
    OPTION_TWO = "option_two"

class QueryParams(BaseModel):
    foo: List[str] = Field(Query(
        default_factory=list,
        description="List of foo parameters",
    ))
    bar: MyEnum = Field(Query(
        default=MyEnum.OPTION_ONE,
        description="Enum for bar parameters",
    ))

@ROUTER.get("/endpoint")
async def endpoint(params: QueryParams = Depends()):
    foobar = "something"  # Dummy response
    return {"foobar": foobar}

Resulting Swagger Docs: Swagger Docs

Looks like this solution also shows how to do this.

Set description for query parameter in swagger doc using Pydantic model (FastAPI)

4 Answers4

References

Linked