是否將輸入與輸出使用不同的 OpenAPI 結構描述 { #separate-openapi-schemas-for-input-and-output-or-not }

自從 Pydantic v2 發佈後，生成的 OpenAPI 比以往更精確也更正確。😎

實際上，在某些情況下，同一個 Pydantic 模型在 OpenAPI 中會同時有兩個 JSON Schema：分別用於輸入與輸出，這取決於它是否有預設值。

來看看它如何運作，以及若需要時該如何調整。

作為輸入與輸出的 Pydantic 模型 { #pydantic-models-for-input-and-output }

假設你有一個帶有預設值的 Pydantic 模型，如下所示：

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}

輸入用模型 { #model-for-input }

如果你把這個模型用作輸入，如下所示：

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:15] hl[14] *}

...則 description 欄位將不是必填。因為它的預設值是 None。

文件中的輸入模型 { #input-model-in-docs }

你可以在文件中確認，description 欄位沒有紅色星號，表示不是必填：

<div class="screenshot"> </div>

輸出用模型 { #model-for-output }

但如果你把同一個模型用作輸出，如下所示：

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py hl[19] *}

...由於 description 有預設值，就算你沒有為該欄位回傳任何內容，它仍會有那個預設值。

輸出回應資料的模型 { #model-for-output-response-data }

在互動式文件中試用並檢視回應時，儘管程式碼沒有為其中一個 description 欄位加入任何內容，JSON 回應仍包含預設值（null）：

<div class="screenshot"> </div>

這代表該欄位一定會有值，只是有時候值可能是 None（在 JSON 中為 null）。

因此，使用你 API 的用戶端不必檢查值是否存在，可以假設該欄位一定存在；只是有些情況下它的值會是預設的 None。

在 OpenAPI 中，描述這種情況的方式是將該欄位標記為必填，因為它一定存在。

因此，同一個模型的 JSON Schema 會依用於輸入或輸出而不同：

• 用於輸入時，description 不是必填
• 用於輸出時，description 是必填（且可能為 None，在 JSON 中為 null）

文件中的輸出模型 { #model-for-output-in-docs }

你也可以在文件中檢視輸出模型，name 與 description 都以紅色星號標示為必填：

<div class="screenshot"> </div>

文件中的輸入與輸出模型 { #model-for-input-and-output-in-docs }

如果你查看 OpenAPI 中所有可用的結構描述（JSON Schema），會看到有兩個：Item-Input 與 Item-Output。

對於 Item-Input，description 不是必填，沒有紅色星號。

但對於 Item-Output，description 是必填，有紅色星號。

<div class="screenshot"> </div>

有了 Pydantic v2 的這個特性，你的 API 文件會更精確；若你有自動產生的用戶端與 SDK，它們也會更精確，提供更好的開發者體驗與一致性。🎉

不要分開結構描述 { #do-not-separate-schemas }

不過，在某些情況下，你可能會希望輸入與輸出使用相同的結構描述。

最常見的情境是：你已經有一些自動產生的用戶端程式碼／SDK，目前還不想全部更新；也許之後會做，但不是現在。

在這種情況下，你可以在 FastAPI 中透過參數 separate_input_output_schemas=False 停用這個功能。

/// info

自 FastAPI 0.102.0 起新增 separate_input_output_schemas 的支援。🤓

///

{* ../../docs_src/separate_openapi_schemas/tutorial002_py310.py hl[10] *}

文件中輸入與輸出使用相同結構描述的模型 { #same-schema-for-input-and-output-models-in-docs }

此時輸入與輸出將共用同一個模型結構描述，只有 Item，其中 description 不是必填：

<div class="screenshot"> </div>