背景描述

oapi-codegen 是代碼自動生成工具，其大致邏輯是：（1）編寫遵循 openAPI 規范的 yaml 格式 api 接口文檔；（2）使用 oapi-codegen 使用 yaml 文件生成 gin 框架的 server 端代碼。

除此以外還有其他的工具也具有同等功能，參見：https://ldej.nl/post/generating-go-from-openapi-3。

openAPI 是一套 api 書寫規范，具體規范內容參見：https://swagger.io/specification。

這種生成的 server 端代碼本身就具有請求參數校驗的功能，開發者只需要寫業務校驗即可，而且能時刻保持 api 文檔和代碼的一致性。

oapi-codegen 安裝

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest

這里有個迷惑信息，執行上述命令會出現 warning 提示：

# github.com/deepmap/oapi-codegen/cmd/oapi-codegen
ld: warning: '/private/var/folders/5n/cwh6dp7x6z7_x48x88q7z8_r0000gn/T/go-link-3224665146/go.o' has malformed LC_DYSYMTAB, expected 120 undefined symbols to start at index 15440, found 129 undefined symbols starting at index 75

執行 oapi-codegen -h 命令會出現：

zsh: command not found: oapi-codegen

以為是安裝失敗了[苦笑]。warning 提示不會影響功能，參見：https://github.com/golang/go/issues/61229。下載的 oapi-codegen 命令保存在 ${GOPATH}/bin 路徑下，只需要將該路徑配置到 PATH 中即可。

# 獲取 GOPATH
go env | grep GOPATH
GOPATH="/Users/diegolli/go"# 查看 oapi-codegen
ll /Users/diegolli/go/bin
total 91360
-rwxr-xr-x  1 diegolli  staff    25M May  6  2023 gopls
-rwxr-xr-x  1 diegolli  staff   6.0M Nov 21 18:05 gotip
-rwxr-xr-x  1 diegolli  staff    14M Nov 21 22:36 oapi-codegen# 配置好 PATH 后執行 oapi-codegen
oapi-codegen
Please specify a path to a OpenAPI 3.0 spec file

出現 ”Please specify a path to a OpenAPI 3.0 spec file“ 表示安裝成功。

oapi-codegen 使用

官方提供了使用 demo，但這種方式要依賴 repo 中的腳本，命令行工具不就白裝了嗎。

命令方式：

oapi-codegen -config server.cfg.yaml petstore-expanded.yaml
# 執行完畢后目錄下會生成 petstore-server.gen.go 文件，里面包含 types、spec、gin、client 相關的代碼。

server.cfg.yaml 地址：https://github.com/deepmap/oapi-codegen/blob/master/examples/petstore-expanded/gin/api/server.cfg.yaml

petstore-expanded.yaml 地址：https://github.com/deepmap/oapi-codegen/blob/master/examples/petstore-expanded/petstore-expanded.yaml

server.cfg.yaml 文件中內容還可以用直接用命令行方式書寫，具體寫法見 oapi-codegen -h 。

小結

1. 這篇文檔只是描述了 oapi-codegen 安裝和使用原型，可以基于此做相關功能測試。
2. oapi-codegen 使用的關鍵是寫 yaml 文檔，規范見開頭鏈接。