diff --git a/docs/zh-hant/docs/advanced/additional-responses.md b/docs/zh-hant/docs/advanced/additional-responses.md index 118c65e044..552ce2e235 100644 --- a/docs/zh-hant/docs/advanced/additional-responses.md +++ b/docs/zh-hant/docs/advanced/additional-responses.md @@ -34,7 +34,7 @@ /// -/// info | 說明 +/// note | 注意 `model` 這個鍵不屬於 OpenAPI。 @@ -183,7 +183,7 @@ /// -/// info | 說明 +/// note | 注意 除非你在 `responses` 參數中明確指定不同的媒體型別,否則 FastAPI 會假設回應的媒體型別與主回應類別相同(預設為 `application/json`)。 diff --git a/docs/zh-hant/docs/advanced/advanced-dependencies.md b/docs/zh-hant/docs/advanced/advanced-dependencies.md index 559ca245fa..880d92ce99 100644 --- a/docs/zh-hant/docs/advanced/advanced-dependencies.md +++ b/docs/zh-hant/docs/advanced/advanced-dependencies.md @@ -98,7 +98,7 @@ checker(q="somequery") 這個行為在 0.118.0 被還原,使得 `yield` 之後的結束程式碼會在回應送出之後才被執行。 -/// info | 資訊 +/// note | 注意 如下所見,這與 0.106.0 之前的行為非常類似,但對一些邊界情況做了多項改進與錯誤修正。 diff --git a/docs/zh-hant/docs/advanced/custom-response.md b/docs/zh-hant/docs/advanced/custom-response.md index c8355937c8..76631e37e5 100644 --- a/docs/zh-hant/docs/advanced/custom-response.md +++ b/docs/zh-hant/docs/advanced/custom-response.md @@ -41,7 +41,7 @@ FastAPI 預設回傳 JSON 回應。 {* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *} -/// info +/// note 參數 `response_class` 也會用來定義回應的「media type」。 @@ -65,7 +65,7 @@ FastAPI 預設回傳 JSON 回應。 /// -/// info +/// note 當然,實際的 `Content-Type` 標頭、狀態碼等,會來自你回傳的 `Response` 物件。 diff --git a/docs/zh-hant/docs/advanced/dataclasses.md b/docs/zh-hant/docs/advanced/dataclasses.md index a18b421c42..0a673889eb 100644 --- a/docs/zh-hant/docs/advanced/dataclasses.md +++ b/docs/zh-hant/docs/advanced/dataclasses.md @@ -18,7 +18,7 @@ FastAPI 建立在 **Pydantic** 之上,我之前示範過如何使用 Pydantic 它的運作方式與 Pydantic 模型相同;實際上,底層就是透過 Pydantic 達成的。 -/// info +/// note 請記得,dataclass 無法做到 Pydantic 模型能做的一切。 diff --git a/docs/zh-hant/docs/advanced/events.md b/docs/zh-hant/docs/advanced/events.md index 7def525fa6..60014a90ac 100644 --- a/docs/zh-hant/docs/advanced/events.md +++ b/docs/zh-hant/docs/advanced/events.md @@ -120,7 +120,7 @@ async with lifespan(app): 在這裡,`shutdown` 事件處理器函式會把一行文字 `"Application shutdown"` 寫入檔案 `log.txt`。 -/// info +/// note 在 `open()` 函式中,`mode="a"` 表示「append(附加)」;也就是說,這行文字會加在檔案現有內容之後,而不會覆寫先前的內容。 @@ -152,7 +152,7 @@ async with lifespan(app): 在底層的 ASGI 技術規範中,這屬於 [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html) 的一部分,並定義了 `startup` 與 `shutdown` 兩種事件。 -/// info +/// note 你可以在 [Starlette 的 Lifespan 文件](https://www.starlette.dev/lifespan/) 讀到更多關於 Starlette `lifespan` 處理器的資訊。 diff --git a/docs/zh-hant/docs/advanced/generate-clients.md b/docs/zh-hant/docs/advanced/generate-clients.md index c1aa88ef71..a56877ccd7 100644 --- a/docs/zh-hant/docs/advanced/generate-clients.md +++ b/docs/zh-hant/docs/advanced/generate-clients.md @@ -31,7 +31,6 @@ FastAPI 會自動產生 **OpenAPI 3.1** 規格,因此你使用的任何工具 例如,你可以嘗試: * [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral) -* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi) 其中有些方案也可能是開源或提供免費方案,讓你不需財務承諾就能試用。其他商業的 SDK 產生器也不少,你可以在網路上找到。🤓 diff --git a/docs/zh-hant/docs/advanced/openapi-callbacks.md b/docs/zh-hant/docs/advanced/openapi-callbacks.md index 3b01f42016..8b4af6dd3d 100644 --- a/docs/zh-hant/docs/advanced/openapi-callbacks.md +++ b/docs/zh-hant/docs/advanced/openapi-callbacks.md @@ -167,13 +167,13 @@ https://www.external.org/events/invoices/2expen51ve 此時你已經在先前建立的回呼 router 中,擁有所需的回呼「路徑操作(們)」(也就是「外部開發者」應該在「外部 API」中實作的那些)。 -現在在「你的 API 的路徑操作裝飾器」中使用參數 `callbacks`,將該回呼 router 的屬性 `.routes`(實際上就是一個由路由/「路徑操作」所組成的 `list`)傳入: +現在在「你的 API 的路徑操作裝飾器」中使用參數 `callbacks`,將該回呼 router 的屬性 `.routes` 傳入: {* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *} /// tip -注意你傳給 `callback=` 的不是整個 router 本身(`invoices_callback_router`),而是它的屬性 `.routes`,也就是 `invoices_callback_router.routes`。 +注意你不是把整個 router 本身(`invoices_callback_router`)傳給 `callbacks=`,而是它的 `.routes`,也就是 `invoices_callback_router.routes`。FastAPI 會使用這些路由來產生回呼的 OpenAPI 文件。 /// diff --git a/docs/zh-hant/docs/advanced/openapi-webhooks.md b/docs/zh-hant/docs/advanced/openapi-webhooks.md index 18206c447b..0e5789aa12 100644 --- a/docs/zh-hant/docs/advanced/openapi-webhooks.md +++ b/docs/zh-hant/docs/advanced/openapi-webhooks.md @@ -22,7 +22,7 @@ 這能讓你的使用者更容易實作他們的 API 以接收你的 webhook 請求,甚至可能自動產生部分他們自己的 API 程式碼。 -/// info +/// note Webhook 功能自 OpenAPI 3.1.0 起提供,FastAPI `0.99.0` 以上版本支援。 @@ -36,7 +36,7 @@ Webhook 功能自 OpenAPI 3.1.0 起提供,FastAPI `0.99.0` 以上版本支援 你定義的 webhook 會出現在 OpenAPI 結構描述與自動產生的文件 UI 中。 -/// info +/// note `app.webhooks` 其實就是一個 `APIRouter`,與你在將應用拆分為多個檔案時所使用的型別相同。 diff --git a/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md b/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md index f1607a1da5..e342ccc115 100644 --- a/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md @@ -16,21 +16,15 @@ ### 使用路徑操作函式(path operation function)的名稱作為 operationId { #using-the-path-operation-function-name-as-the-operationid } -如果你想用 API 的函式名稱作為 `operationId`,你可以遍歷所有路徑,並使用各自的 `APIRoute.name` 覆寫每個*路徑操作*的 `operation_id`。 +如果你想用 API 的函式名稱作為 `operationId`,你可以在 `FastAPI` 中傳入自訂的 `generate_unique_id_function`。 -應在加入所有*路徑操作*之後再這麼做。 +該函式會接收每個 `APIRoute` 並回傳該路徑操作要使用的 `operationId`。 -{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2, 12:21, 24] *} - -/// tip - -如果你會手動呼叫 `app.openapi()`,請務必先更新所有 `operationId` 再呼叫。 - -/// +{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py310.py hl[2,5:6,9] *} /// warning -如果你這樣做,必須確保每個*路徑操作函式*都有唯一的名稱, +如果你這樣做,必須確保每個*路徑操作函式*都有唯一的名稱。 即使它們位於不同的模組(Python 檔案)中。 diff --git a/docs/zh-hant/docs/advanced/response-directly.md b/docs/zh-hant/docs/advanced/response-directly.md index 16face2612..c4b8cb0756 100644 --- a/docs/zh-hant/docs/advanced/response-directly.md +++ b/docs/zh-hant/docs/advanced/response-directly.md @@ -10,7 +10,7 @@ /// tip -通常使用 [回應模型](../tutorial/response-model.md) 會有更好的效能,因為那樣會在 Rust 端使用 Pydantic 來序列化資料,而不是直接回傳 `JSONResponse`。 +通常使用 [回應模型](../tutorial/response-model.md) 會有更好的效能,因為那樣會在 Rust 端使用 Pydantic 來序列化資料。 /// @@ -18,7 +18,7 @@ 其實,你可以回傳任何 `Response`,或其任何子類別。 -/// info +/// note `JSONResponse` 本身就是 `Response` 的子類別。 diff --git a/docs/zh-hant/docs/advanced/security/oauth2-scopes.md b/docs/zh-hant/docs/advanced/security/oauth2-scopes.md index 05088be7ed..d0a6ad0140 100644 --- a/docs/zh-hant/docs/advanced/security/oauth2-scopes.md +++ b/docs/zh-hant/docs/advanced/security/oauth2-scopes.md @@ -46,7 +46,7 @@ OAuth2 規格將「scopes」定義為以空白分隔的一串字串列表。 - `instagram_basic` 是 Facebook / Instagram 使用的。 - `https://www.googleapis.com/auth/drive` 是 Google 使用的。 -/// info +/// note 在 OAuth2 中,「scope」只是宣告所需特定權限的一個字串。 @@ -126,7 +126,7 @@ OAuth2 規格將「scopes」定義為以空白分隔的一串字串列表。 {* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *} -/// info | 技術細節 +/// note | 技術細節 `Security` 其實是 `Depends` 的子類別,僅多了一個我們稍後會看到的參數。 diff --git a/docs/zh-hant/docs/advanced/stream-data.md b/docs/zh-hant/docs/advanced/stream-data.md index 0f55ae6516..d28cd35ec4 100644 --- a/docs/zh-hant/docs/advanced/stream-data.md +++ b/docs/zh-hant/docs/advanced/stream-data.md @@ -4,7 +4,7 @@ 但如果你想串流純二進位資料或字串,以下是做法。 -/// info +/// note 已在 FastAPI 0.134.0 新增。 @@ -90,7 +90,7 @@ FastAPI 會如實將每個資料區塊交給 `StreamingResponse`,不會嘗試 而且在許多情況下,讀取它們會是阻塞操作(可能阻塞事件迴圈),因為資料是從磁碟或網路讀取。 -/// info +/// note 上面的範例其實是例外,因為 `io.BytesIO` 物件已在記憶體中,讀取不會阻塞任何東西。 diff --git a/docs/zh-hant/docs/advanced/strict-content-type.md b/docs/zh-hant/docs/advanced/strict-content-type.md index 9d2ffb8430..e4735c3e8f 100644 --- a/docs/zh-hant/docs/advanced/strict-content-type.md +++ b/docs/zh-hant/docs/advanced/strict-content-type.md @@ -81,7 +81,7 @@ http://localhost:8000/v1/agents/multivac 啟用此設定後,缺少 `Content-Type` 標頭的請求會將其主體解析為 JSON,這與舊版 FastAPI 的行為相同。 -/// info | 資訊 +/// note | 注意 此行為與設定新增於 FastAPI 0.132.0。 diff --git a/docs/zh-hant/docs/advanced/websockets.md b/docs/zh-hant/docs/advanced/websockets.md index 57f51bcfbe..29a95498c9 100644 --- a/docs/zh-hant/docs/advanced/websockets.md +++ b/docs/zh-hant/docs/advanced/websockets.md @@ -111,7 +111,7 @@ $ fastapi dev {* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *} -/// info +/// note 因為這是 WebSocket,拋出 `HTTPException` 並沒有意義,因此我們改為拋出 `WebSocketException`。 diff --git a/docs/zh-hant/docs/advanced/wsgi.md b/docs/zh-hant/docs/advanced/wsgi.md index c1baff34ed..944720bb6a 100644 --- a/docs/zh-hant/docs/advanced/wsgi.md +++ b/docs/zh-hant/docs/advanced/wsgi.md @@ -6,7 +6,7 @@ ## 使用 `WSGIMiddleware` { #using-wsgimiddleware } -/// info +/// note 這需要先安裝 `a2wsgi`,例如使用 `pip install a2wsgi`。 diff --git a/docs/zh-hant/docs/deployment/docker.md b/docs/zh-hant/docs/deployment/docker.md index 03b9f2f76e..650873887c 100644 --- a/docs/zh-hant/docs/deployment/docker.md +++ b/docs/zh-hant/docs/deployment/docker.md @@ -132,7 +132,7 @@ Successfully installed fastapi pydantic -/// info | 資訊 +/// note | 注意 還有其他格式與工具可以用來定義與安裝套件相依。 @@ -556,7 +556,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] 如果你有「多個容器」,且每個容器大概都只執行「單一行程」(例如在一個 Kubernetes 叢集中),那你可能會想要一個「獨立的容器」來完成「前置步驟」的工作,並只在單一容器、單一行程中執行,接著才啟動多個複本的工作容器。 -/// info | 資訊 +/// note | 注意 如果你使用 Kubernetes,這大概會是一個 [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)。 diff --git a/docs/zh-hant/docs/deployment/fastapicloud.md b/docs/zh-hant/docs/deployment/fastapicloud.md index 4b6fb86b47..0d5c5e7b1d 100644 --- a/docs/zh-hant/docs/deployment/fastapicloud.md +++ b/docs/zh-hant/docs/deployment/fastapicloud.md @@ -1,26 +1,6 @@ # FastAPI Cloud { #fastapi-cloud } -你可以用「一行指令」把你的 FastAPI 應用程式部署到 [FastAPI Cloud](https://fastapicloud.com)。如果你還沒加入,快去登記等候名單吧!🚀 - -## 登入 { #login } - -請先確認你已經有 **FastAPI Cloud** 帳號(我們已從等候名單邀請你 😉)。 - -然後登入: - -
-/// info
+/// note
請注意,由於**瀏覽器會以特殊且在背景進行的方式處理 Cookie**,因此**不會**輕易允許 **JavaScript** 存取它們。
diff --git a/docs/zh-hant/docs/tutorial/cookie-params.md b/docs/zh-hant/docs/tutorial/cookie-params.md
index cc9d4b6828..e24a87ede5 100644
--- a/docs/zh-hant/docs/tutorial/cookie-params.md
+++ b/docs/zh-hant/docs/tutorial/cookie-params.md
@@ -24,19 +24,19 @@
///
-/// info
+/// note
要宣告 cookies,你需要使用 `Cookie`,否則參數會被當作查詢參數(query parameters)來解析。
///
-/// info
+/// note
-請注意,由於瀏覽器以特殊且在背後處理的方式管理 cookies,它們通常不允許 JavaScript 輕易存取它們。
+請注意,由於**瀏覽器會以特殊方式並在背後處理 cookies**,因此**不**容易讓 **JavaScript** 觸碰到它們。
-如果你前往位於 `/docs` 的 API 文件介面,你可以在你的路徑操作(path operations)的文件中看到 cookies 的說明。
+如果你前往位於 `/docs` 的 **API 文件介面**,你可以在你的*路徑操作(path operations)*中看到 cookies 的**文件**。
-但即使你填入資料並點擊「Execute」,由於該文件介面是以 JavaScript 運作,cookies 不會被送出,你會看到一則錯誤訊息,就好像你沒有填任何值一樣。
+但即使你**填入資料**並點擊「Execute」,由於該文件介面是以 **JavaScript** 運作,cookies 不會被送出,你會看到一則**錯誤**訊息,就好像你沒有填任何值一樣。
///
diff --git a/docs/zh-hant/docs/tutorial/debugging.md b/docs/zh-hant/docs/tutorial/debugging.md
index 1230ed6ccd..9501dec5cd 100644
--- a/docs/zh-hant/docs/tutorial/debugging.md
+++ b/docs/zh-hant/docs/tutorial/debugging.md
@@ -72,7 +72,7 @@ from myapp import app
就不會被執行。
-/// info | 說明
+/// note
想了解更多,參考 [Python 官方文件](https://docs.python.org/3/library/__main__.html)。
diff --git a/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
index bd57116245..0b548b8e86 100644
--- a/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
+++ b/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md
@@ -28,11 +28,11 @@
///
-/// info
+/// note
在這個範例中我們使用了自訂的(虛構的)標頭 `X-Key` 與 `X-Token`。
-但在實際情況下,當你實作安全機制時,使用整合的 [Security utilities(下一章)](../security/index.md) 會獲得更多好處。
+但在實際情況下,當你實作安全機制時,使用整合的 [安全工具(下一章)](../security/index.md) 會獲得更多好處。
///
diff --git a/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md
index 8174dca40b..59d575fb01 100644
--- a/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md
+++ b/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md
@@ -170,7 +170,7 @@ participant tasks as Background tasks
end
```
-/// info
+/// note
只會向用戶端送出「一個回應」。可能是其中一個錯誤回應,或是來自該路徑操作的回應。
diff --git a/docs/zh-hant/docs/tutorial/dependencies/index.md b/docs/zh-hant/docs/tutorial/dependencies/index.md
index 86aea50f0a..04d2019b79 100644
--- a/docs/zh-hant/docs/tutorial/dependencies/index.md
+++ b/docs/zh-hant/docs/tutorial/dependencies/index.md
@@ -49,7 +49,7 @@
然後它只會回傳一個包含這些值的 `dict`。
-/// info | 說明
+/// note | 注意
FastAPI 在 0.95.0 版新增了對 `Annotated` 的支援(並開始建議使用)。
@@ -104,7 +104,7 @@ common_parameters --> read_users
如此一來,你只需撰寫一次共用程式碼,**FastAPI** 會替你的各個「路徑操作」呼叫它。
-/// check | 檢查
+/// tip | 提示
注意,你不必建立特殊的類別並把它傳到 **FastAPI** 去「註冊」或做類似的事。
diff --git a/docs/zh-hant/docs/tutorial/dependencies/sub-dependencies.md b/docs/zh-hant/docs/tutorial/dependencies/sub-dependencies.md
index 50c4e17908..a2a2ac3084 100644
--- a/docs/zh-hant/docs/tutorial/dependencies/sub-dependencies.md
+++ b/docs/zh-hant/docs/tutorial/dependencies/sub-dependencies.md
@@ -35,7 +35,7 @@
{* ../../docs_src/dependencies/tutorial005_an_py310.py hl[23] *}
-/// info
+/// note
注意,在路徑操作函式中我們只宣告了一個相依項 `query_or_cookie_extractor`。
diff --git a/docs/zh-hant/docs/tutorial/first-steps.md b/docs/zh-hant/docs/tutorial/first-steps.md
index d6b1a72e32..8d644abd14 100644
--- a/docs/zh-hant/docs/tutorial/first-steps.md
+++ b/docs/zh-hant/docs/tutorial/first-steps.md
@@ -180,7 +180,7 @@ entrypoint = "backend.main:app"
from backend.main import app
```
-### 搭配路徑使用 `fastapi dev` { #fastapi-dev-with-path }
+### 使用路徑或 `--entrypoint` 命令列選項執行 `fastapi dev` { #fastapi-dev-with-path-or-with-entrypoint-cli-option }
你也可以把檔案路徑傳給 `fastapi dev` 指令,它會自動猜測要使用的 FastAPI app 物件:
@@ -188,29 +188,19 @@ from backend.main import app
$ fastapi dev main.py
```
-但這樣每次執行 `fastapi` 指令時都要記得傳入正確路徑。
-
-此外,其他工具可能找不到它,例如 [VS Code 擴充套件](../editor-support.md) 或 [FastAPI Cloud](https://fastapicloud.com),因此建議在 `pyproject.toml` 中使用 `entrypoint`。
-
-### 部署你的應用程式(可選) { #deploy-your-app-optional }
-
-你可以選擇將你的 FastAPI 應用程式部署到 [FastAPI Cloud](https://fastapicloud.com),如果還沒有,去加入候補名單吧。🚀
-
-如果你已經有 **FastAPI Cloud** 帳號(我們已從候補名單邀請你 😉),你可以用一個指令部署你的應用程式。
-
-部署之前,先確保你已登入:
-
-get 操作
-/// info | `@decorator` 說明
+/// note | `@decorator` 說明
Python 中的 `@something` 語法被稱為「裝飾器」。
diff --git a/docs/zh-hant/docs/tutorial/metadata.md b/docs/zh-hant/docs/tutorial/metadata.md
index 720b5d87cb..6a54724a5d 100644
--- a/docs/zh-hant/docs/tutorial/metadata.md
+++ b/docs/zh-hant/docs/tutorial/metadata.md
@@ -74,9 +74,9 @@
{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}
-/// info | 資訊
+/// note | 注意
-在 [Path Operation Configuration](path-operation-configuration.md#tags) 中閱讀更多關於標籤的內容。
+在 [路徑操作設定](path-operation-configuration.md#tags) 中閱讀更多關於標籤的內容。
///
diff --git a/docs/zh-hant/docs/tutorial/path-operation-configuration.md b/docs/zh-hant/docs/tutorial/path-operation-configuration.md
index 9ca738a98d..8461f25215 100644
--- a/docs/zh-hant/docs/tutorial/path-operation-configuration.md
+++ b/docs/zh-hant/docs/tutorial/path-operation-configuration.md
@@ -72,13 +72,13 @@
{* ../../docs_src/path_operation_configuration/tutorial005_py310.py hl[18] *}
-/// info | 資訊
+/// note | 注意
請注意,`response_description` 專指回應,而 `description` 則是針對整個「路徑操作」的一般描述。
///
-/// check | 檢查
+/// tip
OpenAPI 規範要求每個「路徑操作」都必須有一個回應描述。
diff --git a/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md b/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md
index 68eb837e94..fd8bf0cec1 100644
--- a/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md
+++ b/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md
@@ -8,7 +8,7 @@
{* ../../docs_src/path_params_numeric_validations/tutorial001_an_py310.py hl[1,3] *}
-/// info
+/// note
FastAPI 在 0.95.0 版加入並開始推薦使用 `Annotated`。
@@ -131,7 +131,7 @@ Python 不會對這個 `*` 做任何事,但它會知道後續的所有參數
* `lt`:小於(`l`ess `t`han)
* `le`:小於或等於(`l`ess than or `e`qual)
-/// info
+/// note
你之後會看到的 `Query`、`Path` 與其他類別,都是共同父類別 `Param` 的子類別。
diff --git a/docs/zh-hant/docs/tutorial/path-params.md b/docs/zh-hant/docs/tutorial/path-params.md
index d46e32bb14..4e8d3dd8f5 100644
--- a/docs/zh-hant/docs/tutorial/path-params.md
+++ b/docs/zh-hant/docs/tutorial/path-params.md
@@ -20,7 +20,7 @@
在這個例子裡,`item_id` 被宣告為 `int`。
-/// check
+/// tip
這會在你的函式中提供編輯器支援,包括錯誤檢查、自動完成等。
@@ -34,7 +34,7 @@
{"item_id":3}
```
-/// check
+/// tip
注意你的函式接收(並回傳)的值是 `3`,也就是 Python 的 `int`,而不是字串 `"3"`。
@@ -66,7 +66,7 @@
同樣的錯誤也會在你提供 `float` 而不是 `int` 時出現,例如:[http://127.0.0.1:8000/items/4.2](http://127.0.0.1:8000/items/4.2)
-/// check
+/// tip
因此,搭配相同的 Python 型別宣告,**FastAPI** 會為你進行資料驗證。
@@ -82,7 +82,7 @@
-/// check
+/// tip
同樣地,只要使用那個 Python 型別宣告,**FastAPI** 就會提供自動、互動式的文件(整合 Swagger UI)。
diff --git a/docs/zh-hant/docs/tutorial/query-params-str-validations.md b/docs/zh-hant/docs/tutorial/query-params-str-validations.md
index 0932c8d90f..1c247b0f8e 100644
--- a/docs/zh-hant/docs/tutorial/query-params-str-validations.md
+++ b/docs/zh-hant/docs/tutorial/query-params-str-validations.md
@@ -29,7 +29,7 @@ FastAPI 會因為預設值是 `= None` 而知道 `q` 不是必填。
{* ../../docs_src/query_params_str_validations/tutorial002_an_py310.py hl[1,3] *}
-/// info | 說明
+/// note | 注意
FastAPI 自 0.95.0 版起加入並開始推薦使用 `Annotated`。
@@ -167,7 +167,7 @@ q: str = Query(default="rick")
## 加入正規表示式 { #add-regular-expressions }
-你可以定義參數必須符合的 regular expression `pattern`:
+你可以定義參數必須符合的 正規表示式 `pattern`:
{* ../../docs_src/query_params_str_validations/tutorial004_an_py310.py hl[11] *}
@@ -381,7 +381,7 @@ Pydantic 也有 [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/va
{* ../../docs_src/query_params_str_validations/tutorial015_an_py310.py hl[5,16:19,24] *}
-/// info | 說明
+/// note | 注意
這需搭配 Pydantic 2 或以上版本。😎
@@ -411,7 +411,7 @@ Pydantic 也有 [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/va
#### 隨機項目 { #a-random-item }
-透過 `data.items()` 我們會得到一個包含每個字典項目鍵值對 tuple 的 iterable object。
+透過 `data.items()` 我們會得到一個包含每個字典項目鍵值對 tuple 的 可疊代物件。
我們用 `list(data.items())` 把這個可疊代物件轉成正式的 `list`。
diff --git a/docs/zh-hant/docs/tutorial/query-params.md b/docs/zh-hant/docs/tutorial/query-params.md
index 89c0834565..24b0cb4049 100644
--- a/docs/zh-hant/docs/tutorial/query-params.md
+++ b/docs/zh-hant/docs/tutorial/query-params.md
@@ -65,7 +65,7 @@ http://127.0.0.1:8000/items/?skip=20
在這種情況下,函式參數 `q` 為選用,且預設為 `None`。
-/// check | 注意
+/// tip | 提示
另外請注意,FastAPI 能辨識出路徑參數 `item_id` 是路徑參數,而 `q` 不是,因此 `q` 會被當作查詢參數。
diff --git a/docs/zh-hant/docs/tutorial/request-files.md b/docs/zh-hant/docs/tutorial/request-files.md
index 4e20544ea4..1d95bf0cd4 100644
--- a/docs/zh-hant/docs/tutorial/request-files.md
+++ b/docs/zh-hant/docs/tutorial/request-files.md
@@ -2,7 +2,7 @@
你可以使用 `File` 定義由用戶端上傳的檔案。
-/// info
+/// note
若要接收上傳的檔案,請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。
@@ -28,7 +28,7 @@ $ pip install python-multipart
{* ../../docs_src/request_files/tutorial001_an_py310.py hl[9] *}
-/// info
+/// note
`File` 是直接繼承自 `Form` 的類別。
diff --git a/docs/zh-hant/docs/tutorial/request-form-models.md b/docs/zh-hant/docs/tutorial/request-form-models.md
index f8a0e8c6c5..9bafb0ef7f 100644
--- a/docs/zh-hant/docs/tutorial/request-form-models.md
+++ b/docs/zh-hant/docs/tutorial/request-form-models.md
@@ -2,7 +2,7 @@
你可以使用 **Pydantic 模型** 在 FastAPI 中宣告 **表單欄位**。
-/// info | 說明
+/// note | 注意
要使用表單,首先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。
diff --git a/docs/zh-hant/docs/tutorial/request-forms-and-files.md b/docs/zh-hant/docs/tutorial/request-forms-and-files.md
index c508bf7f7b..2db9e283b4 100644
--- a/docs/zh-hant/docs/tutorial/request-forms-and-files.md
+++ b/docs/zh-hant/docs/tutorial/request-forms-and-files.md
@@ -2,7 +2,7 @@
你可以使用 `File` 與 `Form` 同時定義檔案與表單欄位。
-/// info
+/// note
要接收上傳的檔案與/或表單資料,請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。
diff --git a/docs/zh-hant/docs/tutorial/request-forms.md b/docs/zh-hant/docs/tutorial/request-forms.md
index d38db96f1a..28d50c3af9 100644
--- a/docs/zh-hant/docs/tutorial/request-forms.md
+++ b/docs/zh-hant/docs/tutorial/request-forms.md
@@ -2,7 +2,7 @@
當你需要接收表單欄位而不是 JSON 時,可以使用 `Form`。
-/// info
+/// note
要使用表單,請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。
@@ -32,7 +32,7 @@ $ pip install python-multipart
使用 `Form` 時,你可以宣告與 `Body`(以及 `Query`、`Path`、`Cookie`)相同的設定,包括驗證、範例、別名(例如用 `user-name` 取代 `username`)等。
-/// info
+/// note
`Form` 是一個直接繼承自 `Body` 的類別。
diff --git a/docs/zh-hant/docs/tutorial/response-model.md b/docs/zh-hant/docs/tutorial/response-model.md
index d9ad9d9d15..be276945b1 100644
--- a/docs/zh-hant/docs/tutorial/response-model.md
+++ b/docs/zh-hant/docs/tutorial/response-model.md
@@ -72,7 +72,7 @@ FastAPI 會使用這個 `response_model` 來做所有的資料文件、驗證等
{* ../../docs_src/response_model/tutorial002_py310.py hl[7,9] *}
-/// info | 說明
+/// note | 注意
要使用 `EmailStr`,請先安裝 [`email-validator`](https://github.com/JoshData/python-email-validator)。
@@ -251,7 +251,7 @@ FastAPI 在內部會搭配 Pydantic 做一些事情,來確保不會把類別
}
```
-/// info | 說明
+/// note | 注意
你也可以使用:
diff --git a/docs/zh-hant/docs/tutorial/response-status-code.md b/docs/zh-hant/docs/tutorial/response-status-code.md
index 9ac2e41dab..9ed047fa59 100644
--- a/docs/zh-hant/docs/tutorial/response-status-code.md
+++ b/docs/zh-hant/docs/tutorial/response-status-code.md
@@ -18,7 +18,7 @@
參數 `status_code` 接受一個數字作為 HTTP 狀態碼。
-/// info | 資訊
+/// note | 注意
`status_code` 也可以接收一個 `IntEnum`,例如 Python 的 [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus)。
@@ -27,7 +27,7 @@
它會:
* 在回應中傳回該狀態碼。
-* 在 OpenAPI 結構中如此記錄(因此也會反映在使用者介面中):
+* 在 OpenAPI 構架中如此記錄(因此也會反映在使用者介面中):
diff --git a/docs/zh-hant/docs/tutorial/schema-extra-example.md b/docs/zh-hant/docs/tutorial/schema-extra-example.md
index 1c2caef85b..01c4a217a0 100644
--- a/docs/zh-hant/docs/tutorial/schema-extra-example.md
+++ b/docs/zh-hant/docs/tutorial/schema-extra-example.md
@@ -24,7 +24,7 @@
///
-/// info
+/// note
OpenAPI 3.1.0(自 FastAPI 0.99.0 起使用)新增了對 `examples` 的支援,這是 **JSON Schema** 標準的一部分。
@@ -155,7 +155,7 @@ OpenAPI 也在規範的其他部分新增了 `example` 與 `examples` 欄位:
* `File()`
* `Form()`
-/// info
+/// note
這個舊的、OpenAPI 特定的 `examples` 參數,從 FastAPI `0.103.0` 起改名為 `openapi_examples`。
@@ -171,7 +171,7 @@ OpenAPI 也在規範的其他部分新增了 `example` 與 `examples` 欄位:
JSON Schema 中新的 `examples` 欄位「就是一個 `list`」的範例集合,而不是像 OpenAPI 其他地方(如上所述)那樣附帶額外中繼資料的 `dict`。
-/// info
+/// note
即使 OpenAPI 3.1.0 已發佈並與 JSON Schema 有更簡潔的整合,一段時間內提供自動文件的 Swagger UI 並不支援 OpenAPI 3.1.0(自 5.0.0 版起支援 🎉)。
diff --git a/docs/zh-hant/docs/tutorial/security/first-steps.md b/docs/zh-hant/docs/tutorial/security/first-steps.md
index 7f12ec1a3a..b7db93b506 100644
--- a/docs/zh-hant/docs/tutorial/security/first-steps.md
+++ b/docs/zh-hant/docs/tutorial/security/first-steps.md
@@ -24,7 +24,7 @@
## 執行 { #run-it }
-/// info
+/// note
當你使用 `pip install "fastapi[standard]"` 指令安裝時,[`python-multipart`](https://github.com/Kludex/python-multipart) 套件會隨 FastAPI 自動安裝。
@@ -60,7 +60,7 @@ $ fastapi dev
-/// check | Authorize 按鈕!
+/// tip | Authorize 按鈕!
你會看到一個新的「Authorize」按鈕。
@@ -118,7 +118,7 @@ FastAPI 提供多層抽象的工具來實作這些安全機制。
本例將使用 OAuth2 的 Password 流程,並以 Bearer token 進行驗證;我們會用 `OAuth2PasswordBearer` 類別來完成。
-/// info
+/// note
「Bearer」token 不是唯一選項。
@@ -148,7 +148,7 @@ FastAPI 提供多層抽象的工具來實作這些安全機制。
我們很快也會建立實際的路徑操作。
-/// info
+/// note
如果你是非常嚴格的「Pythonista」,可能不喜歡參數名稱用 `tokenUrl` 而不是 `token_url`。
@@ -176,7 +176,7 @@ oauth2_scheme(some, parameters)
FastAPI 會知道可以使用這個相依性,在 OpenAPI(以及自動產生的 API 文件)中定義一個「安全性方案」。
-/// info | 技術細節
+/// note | 技術細節
FastAPI 之所以知道可以用(相依性中宣告的)`OAuth2PasswordBearer` 類別,在 OpenAPI 中定義安全性方案,是因為它繼承自 `fastapi.security.oauth2.OAuth2`,而後者又繼承自 `fastapi.security.base.SecurityBase`。
diff --git a/docs/zh-hant/docs/tutorial/security/get-current-user.md b/docs/zh-hant/docs/tutorial/security/get-current-user.md
index b223d4823b..c17b6468e1 100644
--- a/docs/zh-hant/docs/tutorial/security/get-current-user.md
+++ b/docs/zh-hant/docs/tutorial/security/get-current-user.md
@@ -52,7 +52,7 @@
///
-/// check | 檢查
+/// tip | 提示
這個依賴系統的設計讓我們可以有不同的依賴(不同的 "dependables"),都回傳 `User` 模型。
diff --git a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md
index abd920ce6f..dba108c749 100644
--- a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md
+++ b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md
@@ -42,7 +42,7 @@ $ pip install pyjwt
-/// info | 說明
+/// note | 注意
如果你打算使用像 RSA 或 ECDSA 這類的數位簽章演算法,應該安裝帶有加密函式庫相依的 `pyjwt[crypto]`。
@@ -213,7 +213,7 @@ JWT 除了用來識別使用者並允許他直接對你的 API 執行操作外
Username: `johndoe`
Password: `secret`
-/// check | 檢查
+/// tip | 提示
注意在程式碼中完全沒有明文密碼「`secret`」,我們只有雜湊後的版本。
diff --git a/docs/zh-hant/docs/tutorial/security/simple-oauth2.md b/docs/zh-hant/docs/tutorial/security/simple-oauth2.md
index 251848aa5a..de0fe386d5 100644
--- a/docs/zh-hant/docs/tutorial/security/simple-oauth2.md
+++ b/docs/zh-hant/docs/tutorial/security/simple-oauth2.md
@@ -32,7 +32,7 @@ OAuth2 規範中,當使用「password flow」(我們現在使用的)時,
- `instagram_basic` 用在 Facebook / Instagram
- `https://www.googleapis.com/auth/drive` 用在 Google
-/// info
+/// note
在 OAuth2 裡,「scope」只是用來宣告特定所需權限的一個字串。
@@ -72,7 +72,7 @@ OAuth2 規範中,當使用「password flow」(我們現在使用的)時,
- 可選的 `client_id`(本例不需要)
- 可選的 `client_secret`(本例不需要)
-/// info
+/// note
`OAuth2PasswordRequestForm` 並不是像 `OAuth2PasswordBearer` 那樣對 **FastAPI** 來說的特殊類別。
@@ -128,7 +128,7 @@ OAuth2 規範中,當使用「password flow」(我們現在使用的)時,
{* ../../docs_src/security/tutorial003_an_py310.py hl[82:85] *}
-#### 關於 `**user_dict**` { #about-user-dict }
+#### 關於 `**user_dict` { #about-user-dict }
`UserInDB(**user_dict)` 的意思是:
@@ -144,7 +144,7 @@ UserInDB(
)
```
-/// info
+/// note
想更完整地了解 `**user_dict`,請回到[**額外模型** 的文件](../extra-models.md#about-user-in-dict)。
@@ -196,7 +196,7 @@ UserInDB(
{* ../../docs_src/security/tutorial003_an_py310.py hl[58:66,69:74,94] *}
-/// info
+/// note
這裡我們一併回傳值為 `Bearer` 的額外標頭 `WWW-Authenticate`,這也是規範的一部分。
diff --git a/docs/zh-hant/docs/tutorial/server-sent-events.md b/docs/zh-hant/docs/tutorial/server-sent-events.md
index ced91e358a..e539f65d8d 100644
--- a/docs/zh-hant/docs/tutorial/server-sent-events.md
+++ b/docs/zh-hant/docs/tutorial/server-sent-events.md
@@ -4,7 +4,7 @@
這與[串流 JSON Lines](stream-json-lines.md)類似,但使用瀏覽器原生支援、透過 [`EventSource` API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) 的 `text/event-stream` 格式。
-/// info
+/// note
在 FastAPI 0.135.0 新增。
diff --git a/docs/zh-hant/docs/tutorial/stream-json-lines.md b/docs/zh-hant/docs/tutorial/stream-json-lines.md
index 204d32ffd3..6276db7887 100644
--- a/docs/zh-hant/docs/tutorial/stream-json-lines.md
+++ b/docs/zh-hant/docs/tutorial/stream-json-lines.md
@@ -2,7 +2,7 @@
當你有一連串資料想以「**串流**」方式傳送時,可以使用 **JSON Lines**。
-/// info
+/// note
在 FastAPI 0.134.0 新增。
@@ -48,7 +48,7 @@ sequenceDiagram
它和 JSON 陣列(相當於 Python 的 list)很像,但不同於用 `[]` 包起來並以 `,` 分隔項目,它是每一行各放一個 JSON 物件,彼此以換行字元分隔。
-/// info
+/// note
重點在於你的應用能夠逐行產生資料,同時用戶端在消耗前一行的資料。
diff --git a/docs/zh-hant/docs/tutorial/testing.md b/docs/zh-hant/docs/tutorial/testing.md
index f6bef5d962..ab9dac93cc 100644
--- a/docs/zh-hant/docs/tutorial/testing.md
+++ b/docs/zh-hant/docs/tutorial/testing.md
@@ -8,7 +8,7 @@
## 使用 `TestClient` { #using-testclient }
-/// info
+/// note
要使用 `TestClient`,請先安裝 [`httpx`](https://www.python-httpx.org)。
@@ -144,7 +144,7 @@ $ pip install httpx
關於如何把資料傳給後端(使用 `httpx` 或 `TestClient`),更多資訊請參考 [HTTPX 文件](https://www.python-httpx.org)。
-/// info
+/// note
請注意,`TestClient` 接收的是可轉為 JSON 的資料,而不是 Pydantic models。