📝 Add docs recommending Union over Optional and migrate source examples (#4908)

* 📝 Add docs recommending Union over Optional

* 📝 Update docs recommending Union over Optional

* 📝 Update source examples for docs, recommend Union over Optional

* 📝 Update highlighted lines with updated source examples

* 📝 Update highlighted lines in Markdown with recent code changes

* 📝 Update docs, use Union instead of Optional

* ♻️ Update source examples to recommend Union over Optional

* 🎨 Update highlighted code in Markdown after moving from Optional to Union
This commit is contained in:
Sebastián Ramírez authored and GitHub committed 2022-05-14 06:59:59 -05:00
1 parent c5be1b0550
commit ca437cdfab
131 files changed
+489 -426

No files matched your search

@@ -72,7 +72,7 @@
但是你可以使用 `Body` 指示 **FastAPI** 将其作为请求体的另一个键进行处理。
```Python hl_lines="21"
```Python hl_lines="22"
{!../../../docs_src/body_multiple_params/tutorial003.py!}
```
@@ -126,7 +126,7 @@ q: str = None
但是,如果你希望它期望一个拥有 `item` 键并在值中包含模型内容的 JSON,就像在声明额外的请求体参数时所做的那样,则可以使用一个特殊的 `Body` 参数 `embed`:
```Python
item: Item = Body(..., embed=True)
item: Item = Body(embed=True)
```
比如:
+2 -2
View File
@@ -31,7 +31,7 @@ FastAPI 提供了简单易用,但功能强大的**<abbr title="也称为组件
依赖项就是一个函数,且可以使用与*路径操作函数*相同的参数:
```Python hl_lines="8-9"
```Python hl_lines="8-11"
{!../../../docs_src/dependencies/tutorial001.py!}
```
@@ -63,7 +63,7 @@ FastAPI 提供了简单易用,但功能强大的**<abbr title="也称为组件
与在*路径操作函数*参数中使用 `Body`、`Query` 的方式相同,声明依赖项需要使用 `Depends` 和一个新的参数:
```Python hl_lines="13 18"
```Python hl_lines="15 20"
{!../../../docs_src/dependencies/tutorial001.py!}
```
@@ -37,7 +37,7 @@ FastAPI 支持创建含**子依赖项**的依赖项。
接下来,就可以使用依赖项:
```Python hl_lines="21"
```Python hl_lines="22"
{!../../../docs_src/dependencies/tutorial005.py!}
```
@@ -43,7 +43,7 @@
因此,你可以将函数声明为:
```Python hl_lines="8"
```Python hl_lines="7"
{!../../../docs_src/path_params_numeric_validations/tutorial002.py!}
```
@@ -55,7 +55,7 @@
Python 不会对该 `*` 做任何事情,但是它将知道之后的所有参数都应作为关键字参数(键值对),也被称为 <abbr title="来自:K-ey W-ord Arg-uments"><code>kwargs</code></abbr>,来调用。即使它们没有默认值。
```Python hl_lines="8"
```Python hl_lines="7"
{!../../../docs_src/path_params_numeric_validations/tutorial003.py!}
```
@@ -30,12 +30,12 @@
{!../../../docs_src/query_params_str_validations/tutorial002.py!}
```
由于我们必须用 `Query(None)` 替换默认值 `None`,`Query` 的第一个参数同样也是用于定义默认值。
由于我们必须用 `Query(default=None)` 替换默认值 `None`,`Query` 的第一个参数同样也是用于定义默认值。
所以:
```Python
q: str = Query(None)
q: Union[str, None] = Query(default=None)
```
...使得参数可选,等同于:
@@ -49,7 +49,7 @@ q: str = None
然后,我们可以将更多的参数传递给 `Query`。在本例中,适用于字符串的 `max_length` 参数:
```Python
q: str = Query(None, max_length=50)
q: Union[str, None] = Query(default=None, max_length=50)
```
将会校验数据,在数据无效时展示清晰的错误信息,并在 OpenAPI 模式的*路径操作*中记录该参​​数。
@@ -58,7 +58,7 @@ q: str = Query(None, max_length=50)
你还可以添加 `min_length` 参数:
```Python hl_lines="9"
```Python hl_lines="10"
{!../../../docs_src/query_params_str_validations/tutorial003.py!}
```
@@ -66,7 +66,7 @@ q: str = Query(None, max_length=50)
你可以定义一个参数值必须匹配的<abbr title="正则表达式或正则是定义字符串搜索模式的字符序列。">正则表达式</abbr>:
```Python hl_lines="10"
```Python hl_lines="11"
{!../../../docs_src/query_params_str_validations/tutorial004.py!}
```
@@ -110,7 +110,7 @@ q: str = None
但是现在我们正在用 `Query` 声明它,例如:
```Python
q: str = Query(None, min_length=3)
q: Union[str, None] = Query(default=None, min_length=3)
```
因此,当你在使用 `Query` 且需要声明一个值是必需的时,可以将 `...` 用作第一个参数值:
+1 -1
View File
@@ -94,7 +94,7 @@ FastAPI 将使用此 `response_model` 来:
{!../../../docs_src/response_model/tutorial004.py!}
```
* `description: Optional[str] = None` 具有默认值 `None`。
* `description: Union[str, None] = None` 具有默认值 `None`。
* `tax: float = 10.5` 具有默认值 `10.5`.
* `tags: List[str] = []` 具有一个空列表作为默认值: `[]`.
@@ -33,7 +33,7 @@
比如,你可以将请求体的一个 `example` 传递给 `Body`:
```Python hl_lines="21-26"
```Python hl_lines="20-25"
{!../../../docs_src/schema_extra_example/tutorial003.py!}
```