快捷導(dǎo)航

React掌握openapi-typescript-codegen快速生成API客戶端代碼的過程

更新時間：2024年11月15日 10:36:42 作者：亦世凡華、

openapi-typescript-codegen是一個開源工具,用于根據(jù)OpenAPI規(guī)范自動生成TypeScript代碼,包括類型定義和API客戶端代碼,它幫助開發(fā)者節(jié)省手動編寫代碼的時間,提高開發(fā)效率,感興趣的朋友一起看看吧

今天深入探索一個神奇的工具——openapi-typescript-codegen。它不僅能夠幫助你快速生成TS代碼，還能讓你的API請求更加高效、類型安全，讓開發(fā)者擺脫手動編寫冗長請求代碼的困擾，專注于實現(xiàn)業(yè)務(wù)邏輯。接下來讓我們一起來了解它的強大功能和使用技巧，提升你的開發(fā)體驗！

openapi-typescript-codegen：根據(jù)OpenAPI規(guī)范自動生成TS代碼的開源工具，OpenAPI 是一種廣泛使用的API規(guī)范，能夠描述RESTful API的結(jié)構(gòu)和行為，包括請求、響應(yīng)、數(shù)據(jù)模型等內(nèi)容，而openapi-typescript-codegen這個工具正是利用OpenAPI規(guī)范，自動化地為開發(fā)者生成與之匹配的TS類型定義和API客戶端代碼，也就是說作為前端的你不再需要根據(jù)后端提供的接口編寫接口函數(shù)，直接一鍵就可以生成接口函數(shù)，大大提高了編程效率！

如果想了解該開源工具的源碼，可以隨時訪問官網(wǎng) 進(jìn)行查閱，這里不再贅述，接下來博主就對這個開源工具進(jìn)行一個簡單的介紹！

openapi-typescript-codegen的作用如下所示：

1）自動生成TS類型：通過讀取OpenAPI規(guī)范文件，生成與之對應(yīng)的TS類型定義，這樣直接在代碼中使用這些類型，而無需手動編寫類型聲明確保類型安全。

2）生成API客戶端代碼：生成用于與API交互的客戶端代碼，包括自動生成請求函數(shù)、錯誤處理、請求參數(shù)的類型化等。

3）簡化與API的集成：幫助快速生成與API交互所需的所有代碼，避免了手動構(gòu)建請求、解析響應(yīng)等繁瑣的工作，提高了開發(fā)效率。

4）保持同步與API規(guī)范：通過直接從OpenAPI規(guī)范中生成代碼，確保每次 API 更新時相關(guān)的客戶端代碼都能自動同步，避免了手動更新的繁瑣和遺漏。

通過官方文檔的介紹，我們可以知道我們使用該開源工具的優(yōu)勢所在：

總之其是一個非常有意義的工具，特別適用于需要與第三方或內(nèi)部API進(jìn)行頻繁交互的TS項目，幫助開發(fā)者減少了手動編寫重復(fù)代碼的工作量，確保了代碼的類型安全和可靠性，同時能夠與API文檔保持同步，減少了開發(fā)中的錯誤和不一致問題，具體想了解的請查閱官網(wǎng)，這里不再贅述：

借助該工具開發(fā)者不僅能提高開發(fā)效率，還能享受更加流暢和高效的工作體驗，接下來博主就講解一下如何對該開源工具使用進(jìn)行講解，不足之處還請見諒！

接下來介紹如何快速上手openapi-typescript-codegen，幫助開發(fā)者如何在項目中輕松生成與API交互所需的代碼，提升開發(fā)效率并確保類型安全，在官方文檔中提供了該工具使用的一些核心命令，如下所示：

$ openapi --help
  Usage: openapi [options]
  Options:
    -V, --version             output the version number
    -i, --input <value>       OpenAPI specification, can be a path, url or string content (required)
    -o, --output <value>      Output directory (required)
    -c, --client <value>      HTTP client to generate [fetch, xhr, node, axios, angular] (default: "fetch")
    --name <value>            Custom client class name
    --useOptions              Use options instead of arguments
    --useUnionTypes           Use union types instead of enums
    --exportCore <value>      Write core files to disk (default: true)
    --exportServices <value>  Write services to disk (default: true)
    --exportModels <value>    Write models to disk (default: true)
    --exportSchemas <value>   Write schemas to disk (default: false)
    --indent <value>          Indentation options [4, 2, tab] (default: "4")
    --postfixServices         Service name postfix (default: "Service")
    --postfixModels           Model name postfix
    --request <value>         Path to custom request file
    -h, --help                display help for command
  Examples
    $ openapi --input ./spec.json --output ./generated
    $ openapi --input ./spec.json --output ./generated --client xhr

從上面核心命令舉出的examples我們可以知道，該工具主要使用的就是這兩個常用命令，這里對其做一個簡單的介紹：

例如：openapi --input ./spec.json --output ./generated --client xhr

1）–input：指定接口文檔的路徑、url 或字符串內(nèi)容（必填）

2）–output：代碼生成的目錄

3）–client：生成的代碼所需要使用的請求庫

作為前端開發(fā)者最常用的請求庫無非就是axios，這里我們終端執(zhí)行如下命令進(jìn)行安裝：

// 首先下載axios
npm install axios
// 然后安裝成功API工具
npm install openapi-typescript-codegen --save-dev

生成命令：裝配置之后我們可以直接在我們的demo項目中進(jìn)行測試一下，項目終端執(zhí)行如下命令可是發(fā)現(xiàn)控制臺報錯無法識別，如下所示：

openapi --input 你的在線swagger.json地址 --output ./src/api --client axios

解決該方法有兩種，一直是直接將開源工具全局安裝，另一種就是使用npx臨時安裝，都可以：

// 全局安裝
npm install openapi-typescript-codegen -g
// 臨時安裝
npx openapi-typescript-codegen --input 你的在線swagger.json地址 --output ./src/api--client axios

如下可以看出我們根據(jù)在線的swagger.json直接生成的API接口代碼：

為了方便后期重新生成最新的接口代碼，我們可以將命令放置在package.json文件中，通過執(zhí)行npm命令快速生成接口代碼，如下所示：

目錄介紹：接下來我們對上面生成的api目錄下的文件代碼進(jìn)行一個簡單的介紹：

1）core：包含接口請求類型限制、接口請求基本設(shè)置、封裝的接口請求request函數(shù)

2）models：包含接口請求函數(shù)中的所有ts類型

3）services：包含所有的請求接口函數(shù)

4）index.ts：所有請求函數(shù)的出口

這里我們可以自定義一個request.ts文件，然后執(zhí)行如下命令，在每次重新生成的api文件中，復(fù)制使用我們自定義的request.ts文件：

// axios基礎(chǔ)封裝
import axios from 'axios'
export const request: any = axios.create({
    baseURL: '服務(wù)器接口根地址',
    timeout: 5000,
})
// 請求攔截器
request.interceptors.request.use((config: any) => {
    // 請求攔截器
    return config
}, (error: any) => {
    return Promise.reject(error)
})
// 響應(yīng)攔截器
request.interceptors.response.use((res: any) => {
    return res.data
},  (error: any) => {
        //處理網(wǎng)絡(luò)錯誤
        let msg = ''
        const status = error.response.status
        switch (status) {
            case 401:
                msg = 'token過期'
                break
            case 403:
                msg = '無權(quán)訪問'
                break
            case 404:
                msg = '請求地址錯誤'
                break
            case 500:
                msg = '服務(wù)器出現(xiàn)問題'
                break
            default:
                msg = '網(wǎng)絡(luò)出現(xiàn)問題'
                break
        }
        return Promise.reject(error)
    }
)

要生成的代碼中執(zhí)行如下命令，該--request參數(shù)告訴生成器不要生成默認(rèn)的request.ts文件，而是復(fù)制指定的自定義文件進(jìn)行使用：

openapi --input swagger地址 --output ./src/api --request ./src/utils/request.ts --client axios

隨便調(diào)用一個函數(shù)：

import { Button } from 'antd';
import { BasicDataService } from './api'
const App = () => {
  const getData = async () => {
    const data = await BasicDataService.basicDataQueryLocation()
    console.log(data)
  }
  getData()
  return (
    <div style={{ display: 'flex', gap: '20px' }}>
      <Button type='primary'>按鈕</Button>
    </div>
  )
}
export default App

結(jié)果被打印了出來：

到此這篇關(guān)于React掌握openapi-typescript-codegen快速生成API客戶端代碼的文章就介紹到這了,更多相關(guān)react openapi-typescript-codegen API內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: