## TypeScript SDK を作成する { #create-a-typescript-sdk }

まずは簡単な FastAPI アプリから始めます:

{* ../../docs_src/generate_clients/tutorial001_py310.py hl[7:9,12:13,16:17,21] *}

ここで、*path operation* はリクエストとレスポンスのペイロードに使用するモデルを定義しており、`Item` と `ResponseMessage` を使っています。

### API ドキュメント { #api-docs }

`/docs` に移動すると、リクエストで送信・レスポンスで受信するデータの**スキーマ**が表示されます:

<img src="/img/tutorial/generate-clients/image01.png">

これらのスキーマは、アプリ内でモデルとして宣言されているため表示されます。

 - CallStart
 - **CacheHit**
 - CallEnd

### Cache Miss

Under a cache miss the normal request events are seen but an additional event shows the presence of the cache.
Cache Miss will be typical if the item has not been read from the network, is uncacheable, or is past it's
lifetime based on Response cache headers.

 - CallStart
 - **CacheMiss**
 - ProxySelectStart
 - ... Standard Events ...
 - CallEnd

///

## 深度嵌套模型 { #deeply-nested-models }

你可以定义任意深度的嵌套模型：

{* ../../docs_src/body_nested_models/tutorial007_py310.py hl[7,12,18,21,25] *}

/// info | 信息

请注意 `Offer` 拥有一组 `Item` 而反过来 `Item` 又是一个可选的 `Image` 列表是如何发生的。

///

## 纯列表请求体 { #bodies-of-pure-lists }

如果你期望的 JSON 请求体的最外层是一个 JSON `array`（即 Python `list`），则可以在路径操作函数的参数中声明此类型，就像声明 Pydantic 模型一样：

```Python
images: list[Image]

在這個例子中，`str` 是傳給 `list` 的型別參數。

///

這表示：「變數 `items` 是一個 `list`，而這個清單中的每個元素都是 `str`」。

這麼做之後，你的編輯器甚至在處理清單裡的項目時也能提供支援：

<img src="/img/python-types/image05.png">

沒有型別時，幾乎不可能做到這點。

請注意，變數 `item` 是清單 `items` 中的一個元素。

即便如此，編輯器仍然知道它是 `str`，並提供相應的支援。

#### Tuple 與 Set { #tuple-and-set }

你也可以用相同方式來宣告 `tuple` 與 `set`：

{* ../../docs_src/python_types/tutorial007_py310.py hl[1] *}

這代表：

	defer batch.Close()

	var wg sync.WaitGroup
	for i := 0; i < int(limit); i++ {
		wg.Add(1)
		go func(key int) {
			defer wg.Done()
			if err := batch.Add(testItem); err != nil {
				t.Errorf("failed to add item %v; %v", key, err)
				return
			}
		}(i)
	}
	wg.Wait()

	batchLen := batch.Len()
	if batchLen != int(limit) {
		t.Fatalf("Expected batch.Len() %v; but got %v", limit, batchLen)
	}

但本指南会大致展示它们的预期用法。

///

### 使用 Pydantic 的 `exclude_unset` 参数 { #using-pydantics-exclude-unset-parameter }

如果要接收部分更新，建议在 Pydantic 模型的 `.model_dump()` 中使用 `exclude_unset` 参数。

比如，`item.model_dump(exclude_unset=True)`。

这会生成一个 `dict`，只包含创建 `item` 模型时显式设置的数据，不包含默认值。

然后再用它生成一个只含已设置（在请求中发送）数据、且省略默认值的 `dict`：

{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}

但本指南會大致示範它們各自的設計用法。

///

### 使用 Pydantic 的 `exclude_unset` 參數 { #using-pydantics-exclude-unset-parameter }

如果要接收部分更新，在 Pydantic 模型的 `.model_dump()` 中使用 `exclude_unset` 參數非常實用。

例如 `item.model_dump(exclude_unset=True)`。

這會產生一個只包含建立 `item` 模型時實際設定過之欄位的 `dict`，不含預設值。

接著你可以用它來生成只包含實際設定（請求中傳來）的資料之 `dict`，省略預設值：

{* ../../docs_src/body_updates/tutorial002_py310.py hl[32] *}

## TypeScript SDK 만들기 { #create-a-typescript-sdk }

간단한 FastAPI 애플리케이션으로 시작해 보겠습니다:

{* ../../docs_src/generate_clients/tutorial001_py310.py hl[7:9,12:13,16:17,21] *}

*경로 처리*에서 요청 페이로드와 응답 페이로드에 사용하는 모델을 `Item`, `ResponseMessage` 모델로 정의하고 있다는 점에 주목하세요.

### API 문서 { #api-docs }

`/docs`로 이동하면, 요청으로 보낼 데이터와 응답으로 받을 데이터에 대한 **스키마(schemas)**가 있는 것을 볼 수 있습니다:

<img src="/img/tutorial/generate-clients/image01.png">

        from fastapi import FastAPI
        from pydantic import BaseModel

        class Item(BaseModel):
            name: str
            description: str | None = None

        app = FastAPI()

        @app.put("/items/{item_id}")
        def replace_item(item_id: str, item: Item):
            return {"message": "Item replaced", "id": item_id}
        ```
        """
        return self.router.put(

///

## Returning a custom `Response` { #returning-a-custom-response }

The example above shows all the parts you need, but it's not very useful yet, as you could have just returned the `item` directly, and **FastAPI** would put it in a `JSONResponse` for you, converting it to a `dict`, etc. All that by default.

Now, let's see how you could use that to return a custom response.