Fastapi: [DOCS] Support OpenAPI example[s] attribute

[simonTurintech]

Hello everyone.
Today I tried to use fastAPI to add an exemple of values for a model, as decribed here.

After a tedious research in the documentation of Pydantic, I managed to go from this implementation:

from fastapi import FastAPI
from pydantic import BaseModel

class CustomModel(BaseModel):
    id: str
    name: str

app = FastAPI()

@app.get("/", response_model=CustomModel)
def root() -> CustomModel:
    return {"message": "Hello World"}

Giving the following result:

To this implementation:

from fastapi import FastAPI
from pydantic import BaseModel

class CustomModel(BaseModel):
    id: str
    name: str

    class Config(object):
        schema_extra = {
            'example': {
                'id': 'n3xR4Ib79h',
                'name': 'John Doe'
            }
        }

app = FastAPI()

@app.get("/", response_model=CustomModel)
def root() -> CustomModel:
    return {"message": "Hello World"}

Giving the following result:

The code used above is introduced in this page of pydantic's documentation.

As this is a behaviour documented in OpenAPI, and as fastAPI can actually provide that behaviour, should it be a good idea to add this to the doc ? It is quite hidden inside pydantic docs, and it could be usefull to other users.

Thank you for your opinion,
Simon

[jmriebold]

There's actually a more straightforward way to do it, though it's not really mentioned in the docs. This should do the trick:

from fastapi import FastAPI, Body
from pydantic import BaseModel

class CustomModel(BaseModel):
    id: str = Body(None, example='n3xR4Ib79h')
    name: str = Body(None, example='John Doe')

The same can be done for query parameters and path parameters, using FastAPI's Query and Path classes, respectively.

In any case, this should definitely be added to the docs. It took me a fair bit of time to find this solution.

[dmontagu]

If anyone wants to make a docs PR adding this, that would be great!

[tiangolo]

Yep, we want to have it in the docs. I just haven't had the time to do it.

[JohnPaton]

@tiangolo I took a swing at this if you want to have a look :)

[tiangolo]

Hey everyone! Thanks for the discussion here, @JohnPaton solved it on #1106 :rocket: :tada:

[github-actions[bot]]

Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues.