:memo: Add Body Schema tutorial section

diff --git a/docs/tutorial/body-schema.md b/docs/tutorial/body-schema.md
new file mode 100644 (file)
index 0000000..ea94810
--- /dev/null
+++ b/docs/tutorial/body-schema.md
@@ -0,0 +1,55 @@
+The same way you can declare additional validation and metadata in endpoint function parameters with `Query`, `Path` and `Body`, you can declare validation and metadata inside of Pydantic models using `Schema`.
+
+## Import Schema
+
+First, you have to import it:
+
+```Python hl_lines="2"
+{!./tutorial/src/body-schema/tutorial001.py!}
+```
+
+!!! warning
+    Notice that `Schema` is imported directly from `pydantic`, not form `fastapi` as are all the rest (`Query`, `Path`, `Body`, etc).
+
+
+## Declare model attributes
+
+You can then use `Schema` with model attributes:
+
+```Python hl_lines="9 10"
+{!./tutorial/src/body-schema/tutorial001.py!}
+```
+
+`Schema` works the same way as `Query`, `Path` and `Body`, it has all the same parameters, etc.
+
+
+!!! info
+    Actually, `Query`, `Path` and others you'll see next are subclasses of a common `Param` which is itself a subclass of Pydantic's `Schema`.
+
+    `Body` is also a subclass of `Schema` directly. And there are others you will see later that are subclasses of `Body`.
+
+!!! tip
+    Notice how each model's attribute with a type, default value and `Schema` has the same structure as an endpoint's function's parameter, with `Schema` instead of `Path`, `Query` and `Body`.
+
+## Schema extras
+
+In `Schema`, `Path`, `Query`, `Body` and others you'll see later, you can declare extra parameters apart from those described before.
+
+Those parameters will be added as-is to the output JSON Schema.
+
+If you know JSON Schema and want to add extra information appart 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 a <a href="http://json-schema.org/latest/json-schema-validation.html#rfc.section.8.5" target="_blank">JSON Schema example</a> field to a body request JSON Schema:
+
+```Python hl_lines="20 21 22 23 24 25"
+{!./tutorial/src/body-schema/tutorial002.py!}
+```
+
+## Recap
+
+You can use Pydantic's `Schema` to declare extra validations and metadata for model attributes.
+
+You can also use the extra keyword arguments to pass additional JSON Schema metadata.
\ No newline at end of file

diff --git a/docs/tutorial/src/body-schema/tutorial001.py b/docs/tutorial/src/body-schema/tutorial001.py
new file mode 100644 (file)
index 0000000..6c8b101
--- /dev/null
+++ b/docs/tutorial/src/body-schema/tutorial001.py
@@ -0,0 +1,17 @@
+from fastapi import Body, FastAPI
+from pydantic import BaseModel, Schema
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+    name: str
+    description: str = Schema(None, title="The description of the item", max_length=300)
+    price: float = Schema(..., gt=0, description="The price must be greater than zero")
+    tax: float = None
+
+
+@app.put("/items/{item_id}")
+async def update_item(*, item_id: int, item: Item = Body(..., embed=True)):
+    results = {"item_id": item_id, "item": item}
+    return results

diff --git a/docs/tutorial/src/body-schema/tutorial002.py b/docs/tutorial/src/body-schema/tutorial002.py
new file mode 100644 (file)
index 0000000..1165fd7
--- /dev/null
+++ b/docs/tutorial/src/body-schema/tutorial002.py
@@ -0,0 +1,29 @@
+from fastapi import Body, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+    name: str
+    description: str = None
+    price: float
+    tax: float = None
+
+
+@app.put("/items/{item_id}")
+async def update_item(
+    *,
+    item_id: int,
+    item: Item = Body(
+        ...,
+        example={
+            "name": "Foo",
+            "description": "A very nice Item",
+            "price": 35.4,
+            "tax": 3.2,
+        },
+    )
+):
+    results = {"item_id": item_id, "item": item}
+    return results

diff --git a/mkdocs.yml b/mkdocs.yml
index 855ea596baa30f408405b7490f6007b8b339cc81..30f803ef2fb65548621bcb90432d78aa0963b1a4 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -25,6 +25,7 @@ nav:
         - Query Parameters - String Validations: 'tutorial/query-params-str-validations.md'
         - Path Parameters - Numeric Validations: 'tutorial/path-params-numeric-validations.md'
         - Body - Multiple Parameters: 'tutorial/body-multiple-params.md'
+        - Body - Schema: 'tutorial/body-schema.md'
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'