:memo: Add Path params and numeric validators docs

diff --git a/docs/tutorial/path-params-numeric-validations.md b/docs/tutorial/path-params-numeric-validations.md
new file mode 100644 (file)
index 0000000..58ef304
--- /dev/null
+++ b/docs/tutorial/path-params-numeric-validations.md
@@ -0,0 +1,103 @@
+The same way you can declare more validations and metadata for query parameters with `Query`, you can declare the same type of validations and metadata for path parameters with `Path`.
+
+## Import Path
+
+First, import `Path` from `fastapi`:
+
+```Python hl_lines="1"
+{!./tutorial/src/path-params-numeric-validations/tutorial001.py!}
+```
+
+## Declare metadata
+
+You can declare all the same parameters as for `Query`.
+
+For example, to declare a `title` metadata value for the path parameter `item_id` you can type:
+
+```Python hl_lines="8"
+{!./tutorial/src/path-params-numeric-validations/tutorial001.py!}
+```
+
+!!! note
+    A path parameter is always required as it has to be part of the path.
+    
+    So, you should declare it with `...` to mark it as required.
+
+    Nevertheless, even if you declared it with `None` or set a default value, it would not affect anything, it would still be always required.
+
+## Order the parameters as you need
+
+Let's say that you want to declare the query parameter `q` as a required `str`.
+
+And you don't need to declare anything else for that parameter, so you don't really need to use `Query`.
+
+But you still need to use `Path` for the `item_id` path parameter.
+
+Python will complain if you put a value with a "default" before a value that doesn't have a "default".
+
+But you can re-order them, and have the value without a default (the query parameter `q`) first.
+
+It doesn't matter for **FastAPI**. It will detect the parameters by their names, types and default declarations (`Query`, `Path`, etc), it doesn't care about the order.
+
+So, you can declare your function as:
+
+```Python hl_lines="8"
+{!./tutorial/src/path-params-numeric-validations/tutorial002.py!}
+```
+
+## Order the parameters as you need, tricks
+
+If you want to declare the `q` query parameter without a `Query` nor any default value, and the path parameter `item_id` using `Path`, and have them in a different order, Python has a little special syntax for that.
+
+Pass `*`, as the first parameter of the function.
+
+Python won't do anything with that `*`, but it will know that all the following parameters should be called as keyword arguments (key-value pairs), also known as <abbr title="From: K-ey W-ord Arg-uments"><code>kwargs</code></abbr>. Even if they don't have a default value.
+
+```Python hl_lines="8"
+{!./tutorial/src/path-params-numeric-validations/tutorial003.py!}
+```
+
+## Number validations: greater than or equal
+
+With `Query` and `Path` (and other's you'll see later) you can declare string constraints, but also number constraints.
+
+Here, with `ge=1`, `item_id` will need to be an integer number "`g`reater than or `e`qual" to `1`.
+
+```Python hl_lines="8"
+{!./tutorial/src/path-params-numeric-validations/tutorial004.py!}
+```
+## Number validations: greater than and less than or equal
+
+The same applies for:
+
+* `gt`: `g`reater `t`han
+* `le`: `l`ess than or `e`qual
+
+```Python hl_lines="9"
+{!./tutorial/src/path-params-numeric-validations/tutorial005.py!}
+```
+
+## Number validations: floats, greater than and less than
+
+Number validations also work for `float` values.
+
+Here's where it becomes important to be able to declare <abbr title="greater than"><code>gt</code></abbr> and not just <abbr title="greater than or equal"><code>ge</code></abbr>. As with it you can require, for example, that a value must be greater than `0`, even if it is less than `1`.
+
+So, `0.5` would be a valid value. But `0.0` or `0` would not.
+
+And the same for <abbr title="less than"><code>lt</code></abbr>.
+
+```Python hl_lines="11"
+{!./tutorial/src/path-params-numeric-validations/tutorial006.py!}
+```
+
+## Recap
+
+With `Query`, `Path` (and others you haven't seen yet) you can declare [metadata and string validations (the previous chapter)](/tutorial/query-params-str-validations).
+
+And you can also declare numeric validations:
+
+* `gt`: `g`reater `t`han
+* `ge`: `g`reater than or `e`qual
+* `lt`: `l`ess `t`han
+* `le`: `l`ess than or `e`qual

diff --git a/docs/tutorial/query-params-str-validations.md b/docs/tutorial/query-params-str-validations.md
index 7f1e45a1898eecfe0c7721a094139f3a9121fc0b..8d13cc4dbb8f0b5b7930eddab2b055ae68fb6ce6 100644 (file)
--- a/docs/tutorial/query-params-str-validations.md
+++ b/docs/tutorial/query-params-str-validations.md
@@ -179,3 +179,24 @@ Then pass the parameter `deprecated=True` to `Query`:
 The docs will show it like this:
 
 <img src="/img/tutorial/query-params-str-validations/image01.png">
+
+## Recap
+
+You can declare additional validations and metadata for your parameters.
+
+Generic validations and metadata:
+
+* `alias`
+* `title`
+* `description`
+* `deprecated`
+
+Validations specific for strings:
+
+* `min_length`
+* `max_length`
+* `regex`
+
+In these examples you saw how to declare validations for `str` values.
+
+See the next sections to see how to declare validations for other types, like numbers.
\ No newline at end of file

diff --git a/docs/tutorial/src/path-params-numeric-validations/tutorial001.py b/docs/tutorial/src/path-params-numeric-validations/tutorial001.py
new file mode 100644 (file)
index 0000000..fc19118
--- /dev/null
+++ b/docs/tutorial/src/path-params-numeric-validations/tutorial001.py
@@ -0,0 +1,14 @@
+from fastapi import FastAPI, Path, Query
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+async def read_items(
+    item_id: int = Path(..., title="The ID of the item to get"),
+    q: str = Query(None, alias="item-query"),
+):
+    results = {"item_id": item_id}
+    if q:
+        results.update({"q": q})
+    return results

diff --git a/docs/tutorial/src/path-params-numeric-validations/tutorial002.py b/docs/tutorial/src/path-params-numeric-validations/tutorial002.py
new file mode 100644 (file)
index 0000000..57ca50e
--- /dev/null
+++ b/docs/tutorial/src/path-params-numeric-validations/tutorial002.py
@@ -0,0 +1,13 @@
+from fastapi import FastAPI, Path
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+async def read_items(
+    q: str, item_id: int = Path(..., title="The ID of the item to get")
+):
+    results = {"item_id": item_id}
+    if q:
+        results.update({"q": q})
+    return results

diff --git a/docs/tutorial/src/path-params-numeric-validations/tutorial003.py b/docs/tutorial/src/path-params-numeric-validations/tutorial003.py
new file mode 100644 (file)
index 0000000..b6b5a19
--- /dev/null
+++ b/docs/tutorial/src/path-params-numeric-validations/tutorial003.py
@@ -0,0 +1,13 @@
+from fastapi import FastAPI, Path
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+async def read_items(
+    *, item_id: int = Path(..., title="The ID of the item to get"), q: str
+):
+    results = {"item_id": item_id}
+    if q:
+        results.update({"q": q})
+    return results

diff --git a/docs/tutorial/src/path-params-numeric-validations/tutorial004.py b/docs/tutorial/src/path-params-numeric-validations/tutorial004.py
new file mode 100644 (file)
index 0000000..2ec7082
--- /dev/null
+++ b/docs/tutorial/src/path-params-numeric-validations/tutorial004.py
@@ -0,0 +1,13 @@
+from fastapi import FastAPI, Path
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+async def read_items(
+    *, item_id: int = Path(..., title="The ID of the item to get", ge=1), q: str
+):
+    results = {"item_id": item_id}
+    if q:
+        results.update({"q": q})
+    return results

diff --git a/docs/tutorial/src/path-params-numeric-validations/tutorial005.py b/docs/tutorial/src/path-params-numeric-validations/tutorial005.py
new file mode 100644 (file)
index 0000000..2809f37
--- /dev/null
+++ b/docs/tutorial/src/path-params-numeric-validations/tutorial005.py
@@ -0,0 +1,15 @@
+from fastapi import FastAPI, Path
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+async def read_items(
+    *,
+    item_id: int = Path(..., title="The ID of the item to get", gt=0, le=1000),
+    q: str,
+):
+    results = {"item_id": item_id}
+    if q:
+        results.update({"q": q})
+    return results

diff --git a/docs/tutorial/src/path-params-numeric-validations/tutorial006.py b/docs/tutorial/src/path-params-numeric-validations/tutorial006.py
new file mode 100644 (file)
index 0000000..0c19579
--- /dev/null
+++ b/docs/tutorial/src/path-params-numeric-validations/tutorial006.py
@@ -0,0 +1,16 @@
+from fastapi import FastAPI, Path, Query
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+async def read_items(
+    *,
+    item_id: int = Path(..., title="The ID of the item to get", ge=0, le=1000),
+    q: str,
+    size: float = Query(..., gt=0, lt=10.5)
+):
+    results = {"item_id": item_id}
+    if q:
+        results.update({"q": q})
+    return results

diff --git a/mkdocs.yml b/mkdocs.yml
index 2a4aca4e13e8294bd546de2d10ffcac572c01406..a88c6f445f1b30614d72b98e429cbc846c4883a0 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -22,7 +22,8 @@ nav:
         - Path Parameters: 'tutorial/path-params.md'
         - Query Parameters: 'tutorial/query-params.md'
         - Request Body: 'tutorial/body.md'
-        - Query Parameters with toppings: 'tutorial/query-params-schema.md'
+        - Query Parameters - string validations: 'tutorial/query-params-str-validations.md'
+        - Path Parameters - numeric validations: 'tutorial/path-params-numeric-validations.md'
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'