oapi-codegen 安装和使用

背景描述

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 文档，规范见开头链接。