tiangolo.fastapi/docs/en/docs/tutorial/schema-extra-example.md

Schema Extra - Example

You can define extra information to go in JSON Schema.

A common use case is to add an example that will be shown in the docs.

There are several ways you can declare extra JSON Schema information.

Pydantic schema_extra

You can declare an example for a Pydantic model using Config and schema_extra, as described in Pydantic's docs: Schema customization:

{!../../../docs_src/schema_extra_example/tutorial001.py!}

That extra info will be added as-is to the output JSON Schema.

Field additional arguments

In Field, Path, Query, Body and others you'll see later, you can also declare extra info for the JSON Schema by passing any other arbitrary arguments to the function, for example, to add an example:

{!../../../docs_src/schema_extra_example/tutorial002.py!}

!!! warning Have in mind that those extra arguments passed won't add any validation, only annotation, for documentation purposes.

Body additional arguments

The same way you can pass extra info to Field, you can do the same with Path, Query, Body, etc.

For example, you can pass an example for a body request to Body:

{!../../../docs_src/schema_extra_example/tutorial003.py!}

Example in the docs UI

With any of the methods above it would look like this in the /docs:

Technical Details

About example vs examples...

JSON Schema defines a field examples in the most recent versions, but OpenAPI is based on an older version of JSON Schema that didn't have examples.

So, OpenAPI defined its own example for the same purpose (as example, not examples), and that's what is used by the docs UI (using Swagger UI).

So, although example is not part of JSON Schema, it is part of OpenAPI, and that's what will be used by the docs UI.

Other info

The same way, you could add your own custom extra info that would be added to the JSON Schema for each model, for example to customize a frontend user interface, etc.