From d544bdf0928a0e18474a8144c03cfee554dc0d65 Mon Sep 17 00:00:00 2001
From: William Hayes <william.s.hayes@gmail.com>
Date: Wed, 29 May 2019 05:43:41 -0400
Subject: [PATCH] :memo: Update docs for paths in path params (#256)

---
 docs/tutorial/path-params.md | 38 +++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/docs/tutorial/path-params.md b/docs/tutorial/path-params.md
index d795b76e4..b7cf9d4df 100644
--- a/docs/tutorial/path-params.md
+++ b/docs/tutorial/path-params.md
@@ -115,6 +115,42 @@ Because path operations are evaluated in order, you need to make sure that the p
 
 Otherwise, the path for `/users/{user_id}` would match also for `/users/me`, "thinking" that it's receiving a parameter `user_id` with a value of `"me"`.
 
+## Path parameters containing paths
+
+Let's say you have a *path operation* with a path `/files/{file_path}`.
+
+But you need `file_path` itself to contain a *path*, like `home/johndoe/myfile.txt`.
+
+So, the URL for that file would be something like: `/files/home/johndoe/myfile.txt`.
+
+### OpenAPI support
+
+OpenAPI doesn't support a way to declare a *path parameter* to contain a *path* inside, as that could lead to scenarios that are difficult to test and define.
+
+Nevertheless, you can still do it in **FastAPI**, using one of the internal tools from Starlette.
+
+And the docs would still work, although not adding any documentation telling that the parameter should contain a path.
+
+### Path convertor
+
+Using an option directly from Starlette you can declare a *path parameter* containing a *path* using a URL like:
+
+```
+/files/{file_path:path}
+```
+
+In this case, the name of the parameter is `file_path`, and the last part, `:path`, tells it that the parameter should match any *path*.
+
+So, you can use it with:
+
+```Python hl_lines="6"
+{!./src/path_params/tutorial004.py!}
+```
+
+!!! tip
+    You could need the parameter to contain `/home/johndoe/myfile.txt`, with a leading slash (`/`).
+
+    In that case, the URL would be: `/files//home/johndoe/myfile.txt`, with a double slash (`//`) between `files` and `home`.
 
 ## Recap
 
@@ -127,4 +163,4 @@ With **FastAPI**, by using short, intuitive and standard Python type declaration
 
 And you only have to declare them once.
 
-That's probably the main visible advantage of **FastAPI** compared to alternative frameworks (apart from the raw performance).
\ No newline at end of file
+That's probably the main visible advantage of **FastAPI** compared to alternative frameworks (apart from the raw performance).