:memo: Add docs for adding example to schema (#1185)

diff --git a/docs/en/docs/tutorial/body-fields.md b/docs/en/docs/tutorial/body-fields.md
index 8792abee718dca6b5efa06608081f0f8c32ec862..28a81e41328bd3b8b100eb718db873d28fb07c52 100644 (file)
--- 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 <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-20" class="external-link" target="_blank">example</a> 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:
-
-<img src="/img/tutorial/body-fields/image01.png">
-
-!!! note "Technical Details"
-    JSON Schema defines a field <a href="https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5" class="external-link" target="_blank">`examples`</a> 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 <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-20" class="external-link" target="_blank">`example`</a> 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 (file)
index 0000000..70c3d18
--- /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 <a href="https://pydantic-docs.helpmanual.io/usage/schema/#schema-customization" class="external-link" target="_blank">Pydantic's docs: Schema customization</a>:
+
+```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`:
+
+<img src="/img/tutorial/body-fields/image01.png">
+
+## Technical Details
+
+About `example` vs `examples`...
+
+JSON Schema defines a field <a href="https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5" class="external-link" target="_blank">`examples`</a> 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 <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-20" class="external-link" target="_blank">`example`</a> 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 6fbaf960cdab33f8ae40f69acfc026dd1ecc0ed6..db78ee2a7f2bdafe6e9bd1b41b56b64a765dd8ce 100644 (file)
--- 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 (file)
index 0000000..cd4d45f
--- /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