前言#

FastAPI 開發大量微服務，時常需要手(A)動(I)撰寫 SDK 給其他服務使用平時公司內部 SDK 主要需求是 Python and TypeScript，

Python 硬需求有: >=3.10、Pydantic>=2、httpx，支援 Sync and Async，uv python manager
TypeScript: zod

聽聞 OpenAPITools/openapi-generator 很久，所以就上手測試了一下

受測者1: OpenAPI-Generator 上手測試#

1
# 取得 FastAPI 的 openapi.json，請事先啟動 server
2
curl -O http://localhost:8000/openapi.json
3

4
# openapi generator 需要 JAVA runtime，直接上 docker
5
# 預設沒 async
6
docker run --rm \
7
  -v "${PWD}:/local" \
8
  openapitools/openapi-generator-cli generate \
9
  -i /local/openapi.json \
10
  -g python \
11
  -o /local/client-python-default \
12
  --additional-properties=packageName=director_credit
13

14
# 支援 async 版本 (aiohttp)
15
docker run --rm \
16
  -v "${PWD}:/local" \
17
  openapitools/openapi-generator-cli generate \
18
  -i /local/openapi.json \
19
  -g python \
20
  -o /local/client-python-asyncio \
21
  --additional-properties=packageName=director_credit,library=asyncio
22

23
# async - httpx
24
docker run --rm \
25
  -v "${PWD}:/local" \
26
  openapitools/openapi-generator-cli generate \
27
  -i /local/openapi.json \
28
  -g python \
29
  -o /local/client-python-httpx \
30
  --additional-properties=packageName=director_credit,library=httpx
31

32
# 其餘設定看這邊 https://openapi-generator.tech/docs/generators/python

產出成果 - httpx#

預設有 pydantic, docs and unittest，不錯小可惜殘留了一點 poetry 2，但 pyproject.toml 遵循 PEP 621，所以也是可以直接用 uv 讀取並建立虛擬環境，這點影響不大

1
❯ tree ./client-python-httpx -I "__pycache__"
2
./client-python-httpx
3
├── README.md
4
├── director_credit
5
│   ├── __init__.py
6
│   ├── api
7
│   │   ├── __init__.py
8
│   │   └── credit_api.py
9
│   ├── api_client.py
10
│   ├── api_response.py
11
│   ├── configuration.py
12
│   ├── exceptions.py
13
│   ├── models
14
│   │   ├── __init__.py
15
│   │   ├── balance_response.py
16
│   │   ├── deduct_request.py
17
│   │   ├── expires_at.py
18
│   │   ├── gift_credit_request.py
19
│   │   ├── gift_credit_response.py
20
│   │   ├── gift_type.py
21
│   │   ├── http_validation_error.py
22
│   │   ├── location_inner.py
23
│   │   ├── refund_request.py
24
│   │   ├── subscription_request.py
25
│   │   ├── topup_request.py
26
│   │   ├── transaction_response.py
27
│   │   ├── transaction_type.py
28
│   │   └── validation_error.py
29
│   ├── py.typed
30
│   └── rest.py
31
├── docs
32
│   ├── BalanceResponse.md
33
│   ├── CreditApi.md
34
│   ├── DeductRequest.md
35
│   ├── ExpiresAt.md
36
│   ├── GiftCreditRequest.md
37
│   ├── GiftCreditResponse.md
38
│   ├── GiftType.md
39
│   ├── HTTPValidationError.md
40
│   ├── LocationInner.md
41
│   ├── RefundRequest.md
42
│   ├── SubscriptionRequest.md
43
│   ├── TopupRequest.md
44
│   ├── TransactionResponse.md
45
│   ├── TransactionType.md
46
│   └── ValidationError.md
47
├── git_push.sh
48
├── pyproject.toml
49
├── requirements.txt
50
├── setup.cfg
51
├── setup.py
52
├── test
53
│   ├── __init__.py
54
│   ├── test_balance_response.py
55
│   ├── test_credit_api.py
56
│   ├── test_deduct_request.py
57
│   ├── test_expires_at.py
58
│   ├── test_gift_credit_request.py
59
│   ├── test_gift_credit_response.py
60
│   ├── test_gift_type.py
61
│   ├── test_http_validation_error.py
62
│   ├── test_location_inner.py
63
│   ├── test_refund_request.py
64
│   ├── test_subscription_request.py
65
│   ├── test_topup_request.py
66
│   ├── test_transaction_response.py
67
│   ├── test_transaction_type.py
68
│   └── test_validation_error.py
69
├── test-requirements.txt
70
├── tox.ini
71
└── uv.lock
72

73
6 directories, 64 files

受測者2: Stainless#

Stainless and Speakeasy 算是第一梯隊，Fern 第二梯隊(不過他的 cli 體驗真的不賴) 這邊就只整理 Stainless 上來，因為他的比較能夠呈現商業化 SDK generator 目前的頂點，OpenAI 是使用他們家的

安裝跟處理方式照官網文件，生成很省心，直接 sync + async 都給了

Code quality 非常接近手寫的溫度，沒有模版冷冰冰的感覺，然後多了許多邊緣情境的處理（Streaming, Retry and Pagination)，難怪 OpenAI 使用

直接比較生成結果#

Stainless#

介面非常 Pythonic DX，攤平所有應傳的參數，這對使用 SDK 的用戶來說，非常舒服 Stainless 對 IDE 友善，request > transform

1
    async def deduct(
2
        self,
3
        *,
4
        amount: int,
5
        user_id: str,
6
        idempotency_key: str,
7
        service_name: str | Omit = omit,
8
        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
9
        # The extra values given here take precedence over values defined on the client or passed to this method.
10
        extra_headers: Headers | None = None,
11
        extra_query: Query | None = None,
12
        extra_body: Body | None = None,
13
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
14
    ) -> TransactionResponse:

OpenAPI Generator (httpx)#

非常 Pydantic，這點變得要使用者要先處理好 Pydantic Object instance，會顯得更加繁瑣

1
    @validate_call
2
    async def deduct(
3
        self,
4
        idempotency_key: StrictStr,
5
        deduct_request: DeductRequest,
6
        _request_timeout: Union[
7
            None,
8
            Annotated[StrictFloat, Field(gt=0)],
9
            Tuple[
10
                Annotated[StrictFloat, Field(gt=0)],
11
                Annotated[StrictFloat, Field(gt=0)]
12
            ]
13
        ] = None,
14
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
15
        _content_type: Optional[StrictStr] = None,
16
        _headers: Optional[Dict[StrictStr, Any]] = None,
17
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
18
    ) -> TransactionResponse:

接下來是 LLM 查看我測試的幾個解決方案的一些分析(僅供參考)#

特性	OpenAPI Generator (HTTPX)	Stainless	觀點
模型純度	高 (標準 Pydantic)	中 (含大量 Helper 邏輯)	如果您需要將 Model 拿去其他地方用，OpenAPI Gen 的 Model 比較乾淨。
呼叫彈性	顯式 (with_http_info)	隱式 (.with_raw_response)	風格偏好不同，OpenAPI Gen 的方式比較傳統但明確。
依賴性	低 (僅 httpx, pydantic)	高 (依賴 stainless core)	OpenAPI Gen 產出的碼大部分是自己包含的，不依賴像 stainless-python 這樣的外部 Runtime 套件 (除了 httpx/pydantic)。

🏆 現代 Python SDK 生成器終極比較

維度	Stainless 👑	Speakeasy 🥈	Fern 🥉	OpenAPI (HTTPX)	Liblab
核心技術	httpx	httpx	httpx	httpx	requests
Async 支援	✅ 原生 (True Async)	✅ 原生 (True Async)	✅ 原生 (True Async)	✅ 原生 (True Async)	❌ 模擬 (Thread)
Idempotency	⭐ 自動注入 (UUID)	⭐ 需寫 Hook	⭐ 手動傳參	❌ 手動傳參	⭐ 需寫 Hook
Retry 機制	⭐ 極致 (Header感知)	⭐ 需 Config	⭐ 極致 (Header感知)	❌ 無內建	⭐ 基本 (Chain)
資安 (Auth)	⭐⭐⭐⭐⭐ (直觀)	⭐⭐⭐⭐⭐ (強型別)	⭐⭐⭐⭐⭐ (直觀)	⭐⭐⭐ (Setter)	⭐⭐⭐ (Setter)
程式碼風格	極簡、教科書級	標準、Pydantic	極簡、Pythonic	略顯繁瑣	複雜 (責任鏈)
開源/商業	💰 商業付費	💰 商業 (有免費層)	💰 商業 (有免費層)	🆓 完全開源	💰 商業