mirror of https://github.com/tiangolo/fastapi.git
Merge branch 'tiangolo:master' into master
This commit is contained in:
Dauletkhan Assanov
GitHub
commit
383ef95248
|
|
@ -11,6 +11,11 @@ hide:
|
|||
|
||||
* ✏️ Fix link in `fastapi-cli.md`. PR [#11524](https://github.com/tiangolo/fastapi/pull/11524) by [@svlandeg](https://github.com/svlandeg).
|
||||
|
||||
### Translations
|
||||
|
||||
* 🌐 Add Chinese translation for `docs/zh/docs/how-to/configure-swagger-ui.md`. PR [#11501](https://github.com/tiangolo/fastapi/pull/11501) by [@Lucas-lyh](https://github.com/Lucas-lyh).
|
||||
* 🌐 Update Chinese translation for `/docs/advanced/security/http-basic-auth.md`. PR [#11512](https://github.com/tiangolo/fastapi/pull/11512) by [@nick-cjyx9](https://github.com/nick-cjyx9).
|
||||
|
||||
### Internal
|
||||
|
||||
* 👥 Update FastAPI People. PR [#11511](https://github.com/tiangolo/fastapi/pull/11511) by [@tiangolo](https://github.com/tiangolo).
|
||||
|
|
|
|||
|
|
@ -14,15 +14,32 @@ HTTP 基础授权让浏览器显示内置的用户名与密码提示。
|
|||
|
||||
## 简单的 HTTP 基础授权
|
||||
|
||||
* 导入 `HTTPBsic` 与 `HTTPBasicCredentials`
|
||||
* 使用 `HTTPBsic` 创建**安全概图**
|
||||
* 导入 `HTTPBasic` 与 `HTTPBasicCredentials`
|
||||
* 使用 `HTTPBasic` 创建**安全概图**
|
||||
* 在*路径操作*的依赖项中使用 `security`
|
||||
* 返回类型为 `HTTPBasicCredentials` 的对象：
|
||||
* 包含发送的 `username` 与 `password`
|
||||
|
||||
```Python hl_lines="2 6 10"
|
||||
{!../../../docs_src/security/tutorial006.py!}
|
||||
```
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="4 8 12"
|
||||
{!> ../../../docs_src/security/tutorial006_an_py39.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.8+"
|
||||
|
||||
```Python hl_lines="2 7 11"
|
||||
{!> ../../../docs_src/security/tutorial006_an.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.8+ non-Annotated"
|
||||
|
||||
!!! tip
|
||||
尽可能选择使用 `Annotated` 的版本。
|
||||
|
||||
```Python hl_lines="2 6 10"
|
||||
{!> ../../../docs_src/security/tutorial006.py!}
|
||||
```
|
||||
|
||||
第一次打开 URL（或在 API 文档中点击 **Execute** 按钮）时，浏览器要求输入用户名与密码：
|
||||
|
||||
|
|
@ -34,13 +51,35 @@ HTTP 基础授权让浏览器显示内置的用户名与密码提示。
|
|||
|
||||
使用依赖项检查用户名与密码是否正确。
|
||||
|
||||
为此要使用 Python 标准模块 <a href="https://docs.python.org/3/library/secrets.html" class="external-link" target="_blank">`secrets`</a> 检查用户名与密码：
|
||||
为此要使用 Python 标准模块 <a href="https://docs.python.org/3/library/secrets.html" class="external-link" target="_blank">`secrets`</a> 检查用户名与密码。
|
||||
|
||||
```Python hl_lines="1 11-13"
|
||||
{!../../../docs_src/security/tutorial007.py!}
|
||||
```
|
||||
`secrets.compare_digest()` 需要仅包含 ASCII 字符（英语字符）的 `bytes` 或 `str`，这意味着它不适用于像`á`一样的字符，如 `Sebastián`。
|
||||
|
||||
这段代码确保 `credentials.username` 是 `"stanleyjobson"`，且 `credentials.password` 是`"swordfish"`。与以下代码类似：
|
||||
为了解决这个问题，我们首先将 `username` 和 `password` 转换为使用 UTF-8 编码的 `bytes` 。
|
||||
|
||||
然后我们可以使用 `secrets.compare_digest()` 来确保 `credentials.username` 是 `"stanleyjobson"`，且 `credentials.password` 是`"swordfish"`。
|
||||
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="1 12-24"
|
||||
{!> ../../../docs_src/security/tutorial007_an_py39.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.8+"
|
||||
|
||||
```Python hl_lines="1 12-24"
|
||||
{!> ../../../docs_src/security/tutorial007_an.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.8+ non-Annotated"
|
||||
|
||||
!!! tip
|
||||
尽可能选择使用 `Annotated` 的版本。
|
||||
|
||||
```Python hl_lines="1 11-21"
|
||||
{!> ../../../docs_src/security/tutorial007.py!}
|
||||
```
|
||||
这类似于：
|
||||
|
||||
```Python
|
||||
if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
|
||||
|
|
@ -102,6 +141,23 @@ if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
|
|||
|
||||
检测到凭证不正确后，返回 `HTTPException` 及状态码 401（与无凭证时返回的内容一样），并添加请求头 `WWW-Authenticate`，让浏览器再次显示登录提示：
|
||||
|
||||
```Python hl_lines="15-19"
|
||||
{!../../../docs_src/security/tutorial007.py!}
|
||||
```
|
||||
=== "Python 3.9+"
|
||||
|
||||
```Python hl_lines="26-30"
|
||||
{!> ../../../docs_src/security/tutorial007_an_py39.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.8+"
|
||||
|
||||
```Python hl_lines="26-30"
|
||||
{!> ../../../docs_src/security/tutorial007_an.py!}
|
||||
```
|
||||
|
||||
=== "Python 3.8+ non-Annotated"
|
||||
|
||||
!!! tip
|
||||
尽可能选择使用 `Annotated` 的版本。
|
||||
|
||||
```Python hl_lines="23-27"
|
||||
{!> ../../../docs_src/security/tutorial007.py!}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -0,0 +1,78 @@
|
|||
# 配置 Swagger UI
|
||||
|
||||
你可以配置一些额外的 <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration" class="external-link" target="_blank">Swagger UI 参数</a>.
|
||||
|
||||
如果需要配置它们，可以在创建 `FastAPI()` 应用对象时或调用 `get_swagger_ui_html()` 函数时传递 `swagger_ui_parameters` 参数。
|
||||
|
||||
`swagger_ui_parameters` 接受一个直接传递给 Swagger UI的字典，包含配置参数键值对。
|
||||
|
||||
FastAPI会将这些配置转换为 **JSON**，使其与 JavaScript 兼容，因为这是 Swagger UI 需要的。
|
||||
|
||||
## 不使用语法高亮
|
||||
|
||||
比如，你可以禁用 Swagger UI 中的语法高亮。
|
||||
|
||||
当没有改变设置时，语法高亮默认启用：
|
||||
|
||||
<img src="/img/tutorial/extending-openapi/image02.png">
|
||||
|
||||
但是你可以通过设置 `syntaxHighlight` 为 `False` 来禁用 Swagger UI 中的语法高亮：
|
||||
|
||||
```Python hl_lines="3"
|
||||
{!../../../docs_src/configure_swagger_ui/tutorial001.py!}
|
||||
```
|
||||
|
||||
...在此之后，Swagger UI 将不会高亮代码:
|
||||
|
||||
<img src="/img/tutorial/extending-openapi/image03.png">
|
||||
|
||||
## 改变主题
|
||||
|
||||
同样地，你也可以通过设置键 `"syntaxHighlight.theme"` 来设置语法高亮主题（注意中间有一个点）：
|
||||
|
||||
```Python hl_lines="3"
|
||||
{!../../../docs_src/configure_swagger_ui/tutorial002.py!}
|
||||
```
|
||||
|
||||
这个配置会改变语法高亮主题：
|
||||
|
||||
<img src="/img/tutorial/extending-openapi/image04.png">
|
||||
|
||||
## 改变默认 Swagger UI 参数
|
||||
|
||||
FastAPI 包含了一些默认配置参数，适用于大多数用例。
|
||||
|
||||
其包括这些默认配置参数：
|
||||
|
||||
```Python
|
||||
{!../../../fastapi/openapi/docs.py[ln:7-23]!}
|
||||
```
|
||||
|
||||
你可以通过在 `swagger_ui_parameters` 中设置不同的值来覆盖它们。
|
||||
|
||||
比如，如果要禁用 `deepLinking`，你可以像这样传递设置到 `swagger_ui_parameters` 中：
|
||||
|
||||
```Python hl_lines="3"
|
||||
{!../../../docs_src/configure_swagger_ui/tutorial003.py!}
|
||||
```
|
||||
|
||||
## 其他 Swagger UI 参数
|
||||
|
||||
查看其他 Swagger UI 参数，请阅读 <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration" class="external-link" target="_blank">docs for Swagger UI parameters</a>。
|
||||
|
||||
## JavaScript-only 配置
|
||||
|
||||
Swagger UI 同样允许使用 **JavaScript-only** 配置对象（例如，JavaScript 函数）。
|
||||
|
||||
FastAPI 包含这些 JavaScript-only 的 `presets` 设置：
|
||||
|
||||
```JavaScript
|
||||
presets: [
|
||||
SwaggerUIBundle.presets.apis,
|
||||
SwaggerUIBundle.SwaggerUIStandalonePreset
|
||||
]
|
||||
```
|
||||
|
||||
这些是 **JavaScript** 对象，而不是字符串，所以你不能直接从 Python 代码中传递它们。
|
||||
|
||||
如果你需要像这样使用 JavaScript-only 配置，你可以使用上述方法之一。覆盖所有 Swagger UI *path operation* 并手动编写任何你需要的 JavaScript。
|
||||
Loading…
Reference in New Issue