activity-openapi-from-code
SKILL.md
活动 OpenAPI 文档（由代码生成）
核心原则
- 一切有据：每个 path、每个 query/form/json 字段、每个响应字段，都能在代码中找到定义或推导来源（含嵌入字段的父类型）。
- 不 Mock：不写虚构的
example值为主张；若代码无注释，说明含义应来自service层逻辑、命名、conf、常量或调用链，并注明推导依据（如internal/service/service.go:GetXxx）。 - 路径与网关一致：
paths的 key 必须是可与servers拼接的完整路径（以/开头）。客户端实际请求路径为：{servers 中选定项的 url}+{path key}（两段之间按 URL 规则拼接，避免重复或缺省斜杠）。参考实现：servers为- url: /时，paths写活动完整前缀，如/activity_v2/<domain>/<action>。
代码溯源顺序（按此顺序阅读）
| 步骤 | 文件/位置 | 提取内容 |
|---|---|---|
| 1 | <活动>/sale_model.go 或等价 *Model |
GetActId()、GetRouter() 的 Domain、SubRouters[].Action |
| 2 | SubRouters[].Handler 指向的 internal/route/*.go |
HTTP 方法、绑定类型 c.ShouldBind、成功/失败响应封装 |
| 3 | internal/store/req.go（及同包其它 req） |
form / json / uri 标签 → OpenAPI 属性名；binding 与嵌入的 actutil.CommonReq |
| 4 | internal/store/rsp.go 或 route 中 SuccessResponse 的变量类型 |
响应 result 的结构与 json 标签 |
| 5 | internal/service/*.go 中对应函数 |
summary/description 的补充语义（状态机、时间窗、错误分支、枚举含义） |
| 6 | internal/conf/conf.go |
活动在文档 info.description 中可写的 ActID、域名等客观配置 |
| 7 | 公共层 | app/activity/common/actutil/http_req.go（CommonReq）、http_rsp.go（统一响应外层） |