OpenAPI Code Generation 產生程式碼

2023-01-09 214 words 2 minutes

https://user-images.githubusercontent.com/6058558/211311413-94731f5e-722a-4770-a6d4-2afce4d64c99.png

Contents

平常我們介接程式規格一改，我們相關串接程式都要寫程式做調整。最近研究 OpenAPI Spec 可以產生串接程式，這邊就來研究看看。

管理方法

有些人不是很喜歡這個工具，認為程式產生出來程式真的跟人的感覺差很多，但其實我們人不需要管理產生出來程式，這邊產生出來獨立一包程式，這邊主專案做依賴關係，你程式包成一層Service，做程式串接。日後要調整規格，直接重新產生程式就可以了。日後想換 Code Generation 工具，直接在 Service 調整就可以方便解決這個問題。

OpenAPI Generator

官方網站

安裝

官網教學使用 npm 安裝，參考:Hello from OpenAPI Generator

1
2
3
4
5
6


# install the latest version of "openapi-generator-cli"
npm install @openapitools/openapi-generator-cli -g
# use a specific version of "openapi-generator-cli"
openapi-generator-cli version-manager set 6.0.0
# Or install it as dev-dependency in your node.js projects
npm install @openapitools/openapi-generator-cli -D

不過我看 Github 上面寫滿多安裝方法，這邊我選擇用 Java

1

Invoke-WebRequest -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.1.0/openapi-generator-cli-6.1.0.jar

參考:官網 Jar 安裝方式

指令

1
2
3
4


# 產生連結 Java 範例程式
java -jar openapi-generator.jar generate -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -g java   -o ./test/
# 產生檔案 NetCore 範例程式(和config.yaml)
java -jar openapi-generator-cli.jar generate -i xxxx.yml -g csharp-dotnet2   -o ./test/ -c config.yaml

支援產生程式清單

詳細官網列出還滿多，請進裡面查看。
Generators List

設定檔

Generators List連結裡面有列很多程式，這邊可以選擇相關程式，裡面有各自 template 設定說明。

如Documentation for the csharp-netcore Generator就想相關設定。

config.yaml

1
2
3


additionalProperties:
  targetFramework: net5.0
  packageName: Com.Xxxx.Api

還算滿簡單的，這邊我有個建議，通常產生程式出來不是用來改的，是用來呼叫的。所以我覺得程式不應該人為調整，有更新再重新產生程式就可以了。

TDX 文件 Generator Code(從頭實作)

下載 OpenAPI jar

1
2


Invoke-WebRequest -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.1.0/openapi-generator-cli-6.1.0.jar
java -jar openapi-generator-cli.jar generate -i xxxx.yml -g csharp-dotnet2   -o ./test/ -c config.yaml

因為我會有三個
config.yaml

1
2
3


additionalProperties:
  targetFramework: net5.0
  packageName: Com.Xxxx.Api

因為 TDX 有很多種 OpenAPI文件，所以在命名的時候需要特別注意。

1
2
3
4
5


java -jar openapi-generator-cli.jar generate -i .\basic-vehicle-openapi.json -g csharp-netcore   -o ./TDX/BasicVehicleV2/ -c .\basic-vehicle-config.yaml

java -jar openapi-generator-cli.jar generate -i .\basic-administrative-openapi.json -g csharp-netcore   -o ./TDX/BasicAdministrativeV2/ -c .\basic-administrative-config.yaml

java -jar openapi-generator-cli.jar generate -i .\advanced-vehicle-openapi.json -g csharp-netcore   -o ./TDX/AdvancedVehicleV2/ -c .\advanced-vehicle-config.yaml