---
# System prepended metadata

title: swagger-typescript-api
tags: [TS]

---

# swagger-typescript-api 使用指南

## 1. 生成 API 文件

首先，創建一個腳本來生成 TypeScript API 文件：

```typescript
import { generateApi } from 'swagger-typescript-api'
import path from 'path'

const generateTypeScriptApi = async () => {
  try {
    generateApi({
      // 指定生成的 API 文件名稱
      name: 'api.ts',

      // 設定輸出路徑，使用 path.resolve 確保跨平台兼容性
      // process.cwd() 返回當前工作目錄，然後拼接相對路徑
      output: path.resolve(process.cwd(), './src/utils/services'),

      // Swagger JSON 文件的 URL，用於生成 API
      url: 'https://test-cloud-api.mhis.pro/swagger/v1/swagger.json',

      // 指定使用 axios 作為 HTTP 客戶端
      httpClientType: 'axios',

      // 從 Swagger 定義中提取請求 Params
      // 這將生成更詳細的類型定義和函數參數
      extractRequestParams: true,

      // 從 Swagger 定義中提取請求 Body
      // 這將為請求體生成詳細的類型定義
      extractRequestBody: true
    })
  } catch (error) {
    console.error('Error generating API:', error)
  }
}
```

這個腳本會從指定的 Swagger JSON URL 生成 TypeScript API 文件。

## 2. 創建 API 服務

接下來，創建一個 API 服務文件，用於配置和攔截請求/響應：

```typescript
import { Api } from './api.ts'

const TIMEOUT_MS = 2 * 60 * 1000
const apiService = new Api({
  baseURL: import.meta.env.PROD ? import.meta.env.VITE_APP_API_URL : import.meta.env.VITE_APP_PROXY_URL,
  timeout: TIMEOUT_MS
})

apiService.instance.interceptors.request.use(
  config => {
    return config
  },
  error => Promise.reject(error)
)

apiService.instance.interceptors.response.use(
  response => {
    return response
  },
  async error => Promise.reject(error)
)

export default apiService
```

這個文件創建了一個 API 服務實例，設置了基本 URL 和超時時間，並添加了請求和響應攔截器。

## 3. 使用 API

最後，在你的應用中使用生成的 API：

```typescript
import apiService from '@/utils/services/api.service.ts'

apiService.api
  .uploadBatchFileCreate()
  .then((response) => console.log(response))
  .catch(logError)
```



## 注意事項

1. 確保在運行生成腳本之前已安裝 `swagger-typescript-api`。
2. 根據你的項目結構調整文件路徑。
3. 根據你的 API 需求修改生成的配置和使用方式。
4. 在實際使用中，記得處理錯誤和添加適當的類型註解。

