用途:在已存在 go.mod 的 Go 项目中加入 OpenAPI 客户端代码生成能力,基于 oapi-codegen 从 OpenAPI 3.0 规范生成带类型的 Go 客户端与模型。
前提:项目根目录已有 go.mod;用户需提供 OpenAPI 3.0 规范(本地文件或 URL)。若规范为 3.1,需提示 oapi-codegen 对 3.1 仅部分支持,建议转换为 3.0 或谨慎测试。
主要能力与用法:先收集规范路径(如 api/openapi.yaml)与客户端包名,并从 go.mod 检测模块路径。随后创建客户端包目录,写入 generate.yaml 配置(client: true + models: true)、generate.go(含 //go:generate 指令,规范路径须相对该文件,如 ../api/openapi.yaml),并创建 internal/apiconfig 包与 cmd/configure.go,提供 configure set/show/use 三个子命令,用于按环境保存与切换 base_url、api_key,配置存于 Viper 配置文件(~/.{{APP_NAME}}.yaml)。
依赖与生成:执行 go get github.com/oapi-codegen/runtime@latest、go mod tidy,再运行 go generate ./...。若存在 justfile,可追加 generate 与 regen 配方(已存在则跳过)。最后用 go build ./... 验证。
限制与注意:生成的 *.gen.go 应提交版本控制;规范变更后需重新执行 go generate ./...;配置文件含 API 密钥,应加入 .gitignore;大型 API 可考虑拆分 models 与 client。具体模板内容见资料中的 references/templates.md,本文未提供。