examples, example, openapi_examples and json_schema_extra are not working with Query Parameter Models - only model fields do.
#13447
-
First Check
Commit to Help
Example Codefrom fastapi import FastAPI, Query
from pydantic import BaseModel, Field
app = FastAPI()
class TestParams(BaseModel):
x: int
y: int
class TestParamsWithJsonExtras(BaseModel):
x: int
y: int
model_config = {
"json_schema_extra": {
"examples": [
{
"x": 1,
"y": 2,
}
]
}
}
class TestParamsWithExample(BaseModel):
x: int = Field(..., example=1)
y: int = Field(..., example=2)
@app.get("/query-with-single-example")
async def query_with_single_example(
test_params: TestParams = Query(..., example={"x": 1, "y": 2}),
):
return test_params
@app.get("/query-with-multiple-examples")
async def query_with_multiple_examples(
test_params: TestParams = Query(..., examples=[{"x": 1, "y": 2}]),
):
return test_params
@app.get("/query-with-openapi-examples")
async def query_with_openapi_examples(
test_params: TestParams = Query(
...,
openapi_examples={
"myexample": {
"summary": "My Example",
"description": "Description",
"value": {"x": 1, "y": 2},
}
},
),
):
return test_params
@app.get("/query-with-schema-extras")
async def query_with_schema_extras(
test_params: TestParamsWithJsonExtras = Query(...),
):
return test_params
@app.get("/query-with-field-examples")
async def query_with_field_examples(
test_params: TestParamsWithExample = Query(...),
):
return test_paramsDescriptionWhen using the Query Parameter Models, the Am i missing something ? Following https://fastapi.tiangolo.com/tutorial/schema-extra-example/ and more specifically this one https://fastapi.tiangolo.com/tutorial/schema-extra-example/#examples-in-json-schema-openapi examples should work with query Also, I tested with Annotated and it does not work either. Operating SystemLinux Operating System DetailsNo response FastAPI Version0.115.11 Pydantic Version2.9.2 Python VersionPython 3.12.4 Additional ContextNo response |
Beta Was this translation helpful? Give feedback.
Replies: 2 comments 1 reply
-
|
This might be related to #13448 |
Beta Was this translation helpful? Give feedback.
-
|
This is how I see it: Query object is designed to manage metadata of a single query parameter. In case of Query Parameter Model you are dealing with multiple parameters, and Query object is not suitable in this case, and the parameters are expected to be managed through Pydantic models. |
Beta Was this translation helpful? Give feedback.
-
|
According to openapi 3.1 spec, there are 3 ways to specify example\examples for 1) "parameters": [
{
"name": "x",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"title": "X"
},
"example": 2
}
]2) "parameters": [
{
"name": "x",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"title": "X"
},
"examples": {
"myexample_1": {
"value": 1
},
"myexample_2": {
"value": 2
}
}
}
]3) "parameters": [
{
"name": "x",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"example": 2,
"title": "X"
}
}
]Here is how you can achieve this: from typing import Annotated
from fastapi import FastAPI, Query
from pydantic import BaseModel, Field
class WithExample(BaseModel):
x: int = Query(..., example=1)
x_annotated: Annotated[int, Query(example=1)]
class WithExamples(BaseModel):
x: int = Query(
..., openapi_examples={"myexample_1": {"value": 1}, "myexample_2": {"value": 2}}
)
x_annotated: Annotated[
int,
Query(
openapi_examples={"myexample_1": {"value": 1}, "myexample_2": {"value": 2}}
),
]
class WithExampleInSchema(BaseModel):
x: int = Field(..., example=1)
x_annotated: Annotated[int, Field(example=1)]
app = FastAPI()
@app.get("/with-example")
async def r1(
test_params: Annotated[WithExample, Query()],
):
return test_params
@app.get("/with-examples")
async def r2(
test_params: Annotated[WithExamples, Query()],
):
return test_params
@app.get("/with-example-in-schema")
async def r3(
test_params: Annotated[WithExampleInSchema, Query()],
):
return test_paramsNotice, that for cases №1 and №2 you should use Variant with |
Beta Was this translation helpful? Give feedback.
According to openapi 3.1 spec, there are 3 ways to specify example\examples for
Query\Path\Header\Cookieparameters:1)
examplefield of parameter object (notice thatexampleis outside theschema):2)
examplesfield of parameter object (notice thatexamplesis outside theschema):