diff --git a/docs/en/docs/tutorial/body-fields.md b/docs/en/docs/tutorial/body-fields.md index 8792abee7..28a81e413 100644 --- a/docs/en/docs/tutorial/body-fields.md +++ b/docs/en/docs/tutorial/body-fields.md @@ -35,37 +35,11 @@ You can then use `Field` with model attributes: !!! tip Notice how each model's attribute with a type, default value and `Field` has the same structure as a *path operation function's* parameter, with `Field` instead of `Path`, `Query` and `Body`. -## JSON Schema extras +## Add extra information -In `Field`, `Path`, `Query`, `Body` and others you'll see later, you can declare extra parameters apart from those described before. +You can declare extra information in `Field`, `Query`, `Body`, etc. And it will be included in the generated JSON Schema. -Those parameters will be added as-is to the output JSON Schema. - -If you know JSON Schema and want to add extra information apart from what we have discussed here, you can pass that as extra keyword arguments. - -!!! warning - Have in mind that extra parameters passed won't add any validation, only annotation, for documentation purposes. - -For example, you can use that functionality to pass an example for a body request: - -```Python hl_lines="20 21 22 23 24 25" -{!../../../docs_src/body_fields/tutorial002.py!} -``` - -Alternately, you can provide these extras on a per-field basis by using additional keyword arguments to `Field`: - -```Python hl_lines="2 8 9 10 11" -{!../../../docs_src/body_fields/tutorial003.py!} -``` - -Either way, in the `/docs` it would look like this: - - - -!!! note "Technical Details" - 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 defines its own `example` for the same purpose (as `example`, not `examples`), and that's what is used by the docs UI (using Swagger UI). +You will learn more about it later to declare examples examples. ## Recap diff --git a/docs/en/docs/tutorial/schema-extra-example.md b/docs/en/docs/tutorial/schema-extra-example.md new file mode 100644 index 000000000..70c3d1846 --- /dev/null +++ b/docs/en/docs/tutorial/schema-extra-example.md @@ -0,0 +1,58 @@ +# 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: + +```Python hl_lines="13 14 15 16 17 18 19 20 21" +{!../../../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`: + +```Python hl_lines="2 8 9 10 11" +{!../../../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`: + +```Python hl_lines="20 21 22 23 24 25" +{!../../../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. diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 6fbaf960c..db78ee2a7 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -33,6 +33,7 @@ nav: - tutorial/body-multiple-params.md - tutorial/body-fields.md - tutorial/body-nested-models.md + - tutorial/schema-extra-example.md - tutorial/extra-data-types.md - tutorial/cookie-params.md - tutorial/header-params.md diff --git a/docs_src/schema_extra_example/tutorial001.py b/docs_src/schema_extra_example/tutorial001.py new file mode 100644 index 000000000..cd4d45f51 --- /dev/null +++ b/docs_src/schema_extra_example/tutorial001.py @@ -0,0 +1,27 @@ +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + description: str = None + price: float + tax: float = None + + class Config: + schema_extra = { + "example": { + "name": "Foo", + "description": "A very nice Item", + "price": 35.4, + "tax": 3.2, + } + } + + +@app.put("/items/{item_id}") +async def update_item(*, item_id: int, item: Item): + results = {"item_id": item_id, "item": item} + return results diff --git a/docs_src/body_fields/tutorial003.py b/docs_src/schema_extra_example/tutorial002.py similarity index 100% rename from docs_src/body_fields/tutorial003.py rename to docs_src/schema_extra_example/tutorial002.py diff --git a/docs_src/body_fields/tutorial002.py b/docs_src/schema_extra_example/tutorial003.py similarity index 100% rename from docs_src/body_fields/tutorial002.py rename to docs_src/schema_extra_example/tutorial003.py