API 的常見使用案例是，您的呼叫有一組可能具有預定義值的參數。以分頁為例，呼叫允許您要求特定頁面的查詢結果。作為產生者，您可能會允許消費者設定每頁的條目數，但您也希望允許消費者取得預定義數量的條目，而無需在每次請求時都傳送它。
使用預設值
這就是default值的作用。在 Swagger 規格中，default允許您為參數、模型（及其屬性）或回應標頭（容器）設定值。當客戶端或伺服器省略這些值時，接收端應採用default值。
default關鍵字的值在 Swagger 規格中略有獨特。它被定義為Any，但旨在「複製」其包含物件的類型。因此，如果您有一個類型為string的參數，則default的值也應為string。顯然，不匹配的類型沒有意義，因為您將宣告該屬性的預設值與允許的類型不同。對於複雜類型的內文參數，default可以表示複雜的預設值。陣列類型的容器也應具有陣列結構作為其預設值。
您可以在規格的以下位置找到default屬性
為什麼要使用預設值？
定義值有幾個好處
- 如前所述，它允許從請求中省略參數/屬性/標頭，簡化流程並最大限度地減少所需的頻寬。
- 它有助於記錄您的 API 行為。如果您指定預設值，您的消費者就知道在回應中會收到什麼。
- 它允許更好的 API 測試，因為測試人員知道未指定容器時的預期結果。
使用預設值時的常見錯誤
使用default值時，可能會有兩種差異
- 為容器定義預設值並將該容器標記為必要，這在某種程度上是矛盾的。如果容器是必要的，它將始終被傳送，並且預設值將永遠不會生效。
- 第二種情況是使用default來提及其容器的範例值。這不是該欄位的正確用法，可能會導致某些 Swagger 工具中出現意外行為。某些容器提供了設定範例值的替代方法。
專業提示
我們對default關鍵字還有另一種用途，那就是截然不同。它可以用在回應部分下，以提及 API 的通用回應。通常，您會描述您成功的響應，但有時您可能會有一種通用的方式來公開錯誤，無論使用哪種 HTTP 狀態碼。在這種情況下，您可以使用default回應並提供它使用的通用結構。
如需更多資訊，請查看規格中的章節 - https://swagger.dev.org.tw/specification/#responsesDefault。