CODEWITHSUNDEEP
pythonfastapi
karsas
karsas

Reputation: 1341

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

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

enter image description here

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

enter image description here

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

Upvotes: 28

Views: 27147

Answers (4)

Jacob Petterle
Jacob Petterle

Reputation: 61

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.

Upvotes: 6

Rohit
Rohit

Reputation: 4158

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.

Upvotes: 3

Sanket Berde
Sanket Berde

Reputation: 6895

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"

Upvotes: 18

JPG
JPG

Reputation: 88499

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,

screenshot

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)

Upvotes: 25

Related Questions