為什麼要用 openapi-generator-cli ?
openapi-generator-cli是一個強大的工具,用於自動生成API客戶端庫、服務器存根和API文件。
簡單說，現在開發API的時候大部分都遵守OpenApi的規範，OpenAPI的採用率和生態系統支持使其成為當前最主要的選擇之一。
當後端開發好API時，可能會提供與OpenAPI相容的API文件，最常見的是 Swagger，用來展示這些文件，可是前端看到這些文件的時候，並不能馬上使用，必須先將文件轉成前端可以用的檔案，例如 .ts 或者 .js 讓前端的框架可以認識並使用API。
除了手動產生之外，最快的方法應該是自動產生，大幅縮短產生API檔案的時間。
安裝 openapi-generator-cli
在安裝 openapi-generator-cli 之前，需要安裝 Java 環境，如果不想安裝Java環境，可以使用 Docker 模式使用。
推薦安裝 Java 環境為 Temurin 的 OpenJDK，安裝後開啟一個新的終端機輸入
java -version
正常的話會看到這樣的畫面，表示正確安裝OpenJDK
接著在終端機畫面中輸入
npm install -g @openapitools/openapi-generator-cli
或是
yarn global add @openapitools/openapi-generator-cli
安裝完成後，進到前端的主目錄底下，輸入
openapi-generator-cli
會產生一個 openapitools.json 的檔案，這是openapi-generator-cli的設定檔，他的結構如下
{
"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"version": "7.7.0"
}
}
設定openapi-generator-cli的Config檔: openapitools.json
先上一個範例程式，我們再解說其中的關鍵地方“。
{
"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"version": "7.7.0",
"generators": {
"v1.0": {
"generatorName": "typescript-axios",
"output": "./src/api-services",
"skipValidateSpec": true,
"inputSpec": "http://localhost:5501/swagger/Default/swagger.json",
"additionalProperties": {
"apiPackage": "apis",
"modelPackage": "models",
"withSeparateModelsAndApi": true
}
}
}
}
}這個範例程式表示要以 typescript-axios 作為輸出結果，並把結果放到 ./src/api-services 目錄底下，使用的來源是 http://localhost:5501/swagger/Default/swagger.json ，並且將Model跟 Api分開 (“withSeparateModelsAndApi”: true)，並把API放到 apis 這個目錄，把model放到 models 這個目錄。
產生之後的目錄結構如下
如果需要更多 additionalProperties 的資訊，可以拜訪 https://openapi-generator.tech/docs/configuration 可以取得更多的資訊。
當我們把設定檔設定完成以後，便要來設定 package.json 這個檔案
設定 package.json 的快速使用指令
接著打開 package.json 這個檔案，你會看到類似如下畫面
在 script 這邊，可能每個系統與專案都不一樣，因此不必要照著修改成一樣的內容，我們要注意的是其中最下面那行 api ，這裡會使用快速指令讓 openapi-generator-cli 開始作業，產生我們要的API檔案。
"api": "openapi-generator-cli generate --generator-key v1.0"
其中應該注意 –generator-key v1.0 這個指令，表示我們將使用 generators 的 v1.0，他在剛剛的 openapitools.json 中有設定。他的位置如下:
使用快速指令
由於我們剛剛在 package.json 設定 api 的指令，因此我們可以用
npm run api
或者
pnpm api
或者
yaen api
來產生相關的API與MODEL，他產生的過程大致上長這樣:
查看一下目標目錄(./src/api-services) 應該會看到檔案都個別產生出來，models 因為太多檔案了，就不展示了。
使用API
在 vue 檔案中，import 一個 api 方法。
New 出來後，即可使用該 api 方法。
以上就是前端框架Vue中使用 openapi-generator-cli 來自動產生API檔案的快速方法。
