[FEATURE] Way to tie OpenAPI Examples to a pydantic model

The problem I would like to tie a schema example to my pydantic model, but currently the only way to do it is to declare the example when you’re using the model, as far as I can understand. It’s document here: https://fastapi.tiangolo.com/tutorial/body-schema/#schema-extras.

The solution I would like It would be nice if possible to have something like an __example__ attribute on the model that could be tied directly to the the OpenAPI schema itself. Like the first example under Request and Response Body Examples at https://swagger.io/docs/specification/adding-examples/.

Example Something along the lines of this:

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

    __example__ = {
        "name": "Foo",
        "description": "A very nice Item",
        "price": 35.4,
        "tax": 3.2,
    }

I don’t know if that specific method makes sense or is possible or right, but the general idea of tying examples to the schema itself would be nice.

[tiangolo]

For completeness, there are new docs about adding examples that show up in Swagger UI: https://fastapi.tiangolo.com/tutorial/schema-extra-example/

[zamiramir]

Typo: “examples” should be “example”

from fastapi.applications import FastAPI
from pydantic import BaseModel


class Person(BaseModel):
    name: str
    age: int

    class Config:
        schema_extra = {
             'example': [{
                'name': 'John Doe',
                'age': 25,
            }]
        }


app = FastAPI()


@app.get('/router', responses={200: {'model': Person}})
async def handler():
    return "hello world"


if __name__ == '__main__':
    import sys
    import fastapi
    print('python version', sys.version)
    print('fastapi version', fastapi.__version__)
    import json
    print(json.dumps(app.openapi(), indent=2, ensure_ascii=False))

python version 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 16:52:21) [Clang 6.0 (clang-600.0.57)] fastapi version 0.38.1

{
  "openapi": "3.0.2",
  "info": {
    "title": "Fast API",
    "version": "0.1.0"
  },
  "paths": {
    "/router": {
      "get": {
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        },
        "summary": "Handler",
        "operationId": "handler_router_get"
      }
    }
  },
  "components": {
    "schemas": {
      "Person": {
        "title": "Person",
        "required": [
          "name",
          "age"
        ],
        "type": "object",
        "properties": {
          "name": {
            "title": "Name",
            "type": "string"
          },
          "age": {
            "title": "Age",
            "type": "integer"
          }
        },
        "example": [
          {
            "name": "John Doe",
            "age": 25
          }
        ]
      }
    }
  }
}