How to use openapi_examples with Pydantic?

[Zer0x00]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question 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
from fastapi.openapi.models import Example
from pydantic import BaseModel, ConfigDict, Field

app = FastAPI()


class CreateRequest1(BaseModel):
    name: str = Field(..., description="Name of the created item")
    value: str = Field(..., description="Value of the created item")

    model_config = ConfigDict(json_schema_extra={"examples": [{"name": "Item1", "value": "Value1"}]})


class CreateRequest2(BaseModel):
    name: str = Field(..., description="Name of the created item")
    value: str = Field(..., description="Value of the created item")

    model_config = ConfigDict(
        json_schema_extra={
            "openapi_examples": {
                "abc": Example(summary="test", description="test", value={"name": "Item1", "value": "Value1"})
            }
        }
    )


@app.post("/1")
def create_item1(body: CreateRequest1):
    return CreateRequest1.name


@app.post("/2")
def create_item2(body: CreateRequest2):
    return CreateRequest2.name

Description

How can I use openapi_examples from a pydantic model?

CreateRequest1 is just an example how it works with examples
The above example with CreateRequest2 didn't work.

I also couldn't find any example in the documentation.

Operating System

Linux

Operating System Details

No response

FastAPI Version

0.103.1

Pydantic Version

2.3.0

Python Version

3.11.5

Additional Context

No response

[spolloni]

@tiangolo any suggestions here?

[YuriiMotov]

openapi_examples is a parameter of Body, it's not a part of JSON schema (json_schema_extra is supposed to be used to modify the JSON schema).

You can specify examples for request body

from typing import Annotated
from fastapi import Body, FastAPI
from fastapi.openapi.models import Example
from pydantic import BaseModel, Field

app = FastAPI()

class CreateRequest2(BaseModel):
    name: str = Field(..., description="Name of the created item")
    value: str = Field(..., description="Value of the created item")

@app.post("/2")
def create_item2(
    body: Annotated[
        CreateRequest2,
        Body(
            openapi_examples={
                "abc": Example(
                    summary="test",
                    description="test",
                    value={"name": "Item1", "value": "Value1"},
                )
            }
        ),
    ],
):
    return CreateRequest2.name

But, there is a tricky thing here: it will only work if you have only one Body parameter in this endpoint. As soon as you add another model or single Body parameter it will stop working.
I explained it in details and showed the way to specify examples for multiple Body parameters here: #10600 (comment)