swaggerx —— Swagger UI + 自动生成的 OpenAPI 3.0 spec
把后台接口的全量清单(路径 / 方法 / 每个接口的 RBAC 权限码) 变成一份机器可读的 OpenAPI 3.0 文档,挂在
/swagger上。
功能
swaggerx 做四件事:
- spec 是从运行期的路由表推出来的,不是另写一份注解。
路由表只有 Hertz 实例自己知道 ⇒
BuildSpec收一个*server.Hertz。 框架/健康/指标端点(/swagger*//healthz//readyz//metrics) 不进业务文档;只收/rapid-admin/v1/前缀的路由。 - 字段级 schema 是反射出来的:json tag 说字段名、指针说可选性、 行尾注释说含义。不用 swaggo 注解 ⇒ 不用给 185+ 个 handler 各加 6-10 行 注释,也不用多一条工具链依赖(185 路由 × 8 行 ≈ 1500 行标注)。
- BasicAuth 闸:
/swagger/doc.json里是全量接口清单, 裸奔等于把攻击面画好送出去 ⇒ 鉴权闸是默认要装的东西,不是可选项。 - 两个框架扩展字段:
x-rbac-code—— 每条接口的 RBAC 权限码,集成方靠它知道"这个接口要什么权限"x-schema-coverage—— 字段级 schema 的覆盖率(路由数 / 写接口数 / 拿到 schema 的写接口数 / 百分比)。覆盖率不藏着,它是可核对的数字。
它不解决:
- 不生成响应体的字段级 schema(只做请求体)。响应体形状由 统一响应体约定,不是每个 DTO 逐个反射。
- 不生成
swag init那样的注解式描述(summary / description 是按 URL 段自动拼的)。 - 不做文档的版本管理(改 handler 不会产生"新版本文档",只有一份活的 spec)。
配置
yaml 侧(swagger: 块)
swagger:
enabled: true
auth:
mode: auto
username: "" # 留空 ⇒ auto 模式下用 "swagger"
password: "" # 留空 ⇒ auto 模式下本次启动随机生成(见启动日志)
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
swagger.enabled |
bool | true |
是否挂载 /swagger 端点。关掉 = 整条端点不存在 |
swagger.auth.mode |
string | auto |
auto / basic / none |
swagger.auth.username |
string | "" |
BasicAuth 用户名。auto 模式下留空 ⇒ 用 "swagger" |
swagger.auth.password |
string | "" |
BasicAuth 密码。auto 模式下留空 ⇒ 本次启动随机生成 |
三种 mode 的行为:
| mode | 行为 |
|---|---|
auto(默认,空值等同) |
配了固定凭据就用固定凭据;没配就本次启动随机生成一个密码并打进启动日志(重启会变) |
basic |
必须配固定凭据,没配直接报错 → 拒绝启动(fail-fast) |
none |
不鉴权。⚠️ 只有本地开发能用 |
⚠️ 凭据建议走环境变量 SWAGGER_AUTH_USERNAME / SWAGGER_AUTH_PASSWORD,
别写进 yaml。
标题与品牌
文档标题不在 swagger: 块里,走 branding: 配置:
branding:
app_name: "" # 平台全名
app_title: "" # 浏览器标签页标题;留空 = 用 app_name
派生顺序:branding.app_title → branding.app_name → system.app_name(服务标识)。
⚠️ 不许在代码里写死项目名 —— 开源通用化要求"改个 yaml 就能换名字"。
代码侧(构造选项)
swaggerx.Mount(h *server.Hertz, mountAt string, info Info, assets fs.FS, auth AuthConfig)
swaggerx.BuildSpec(h *server.Hertz, info Info, rbacCodes map[string]bool) *OpenAPI
swaggerx.BasicAuth(cfg AuthConfig) app.HandlerFunc
swaggerx.SetRBACCodesProvider(fn func() map[string]bool)
swaggerx.SetSchemaSource(dtos map[string]any, docs map[string]map[string]string)
swaggerx.SortPathsStable(spec *OpenAPI)
| 类型 | 说明 |
|---|---|
Info |
Title / Description / Version / BaseURL |
AuthConfig |
Enabled / Username / Password |
OpenAPI |
完整 spec 结构(Paths / Components / Tags / XSchemaCoverage …) |
SchemaCoverage |
Routes / WriteRoutes / WithRequestSchema / Percent |
使用方法
完整示例:examples/swaggerx/main.go。
一、挂载(生产装配在 internal/api/router/router.go)
swaggerx.SetRBACCodesProvider(RBACCodesProvider) // 让每条 route 带 x-rbac-code
swaggerx.SetSchemaSource(v1.RequestDTOs, v1.RequestFieldDocs) // 字段级 schema 的来源
swaggerx.Mount(h, "/swagger", swaggerx.Info{
Title: swaggerDocTitle(cfg),
Description: "Backend API reference. ...",
Version: cfg.System.AppVersion,
BaseURL: "/rapid-admin/v1",
}, swagger.Assets(), swaggerx.AuthConfig{
Enabled: cfg.Swagger.Auth.Enabled,
Username: cfg.Swagger.Auth.Username,
Password: cfg.Swagger.Auth.Password,
})
⚠️ 这层必须挂在全局中间件链之前 —— router.go 里它是第一件注册的事,
所以拿不到 middleware.Recover();本包自己兜 panic(见 safeHandler)。
挂完得到三个路由:
| 路径 | 作用 |
|---|---|
/swagger |
302 跳 /swagger/index.html(浏览器不会自动补 index.html) |
/swagger/doc.json |
OpenAPI 3.0 原始 JSON |
/swagger/*any |
swagger-ui 静态资产 |
二、不挂 UI,只生成 spec
spec := swaggerx.BuildSpec(h, swaggerx.Info{
Title: "示例平台 - 后台 API",
Description: "由框架层 swaggerx 自动生成",
Version: "1.0.0",
BaseURL: "https://api.example.com/rapid-admin/v1",
}, map[string]bool{
"orders:list": true,
"orders:read": true,
"users:list": true,
})
rbacCodes 是权限码表,由 router 包在注册路由时共享进来
(SetRBACCodesProvider);x-rbac-code 的推断是 best-effort:
从 URL 段拼"<资源>:<动作>"再查这张表,同一个 URL 命中多个动作时挑哪个不确定。
三、BasicAuth 闸
auth := swaggerx.AuthConfig{Enabled: true, Username: "docs", Password: "s3cret"}
mw := swaggerx.BasicAuth(auth) // Enabled=false 时返回 nil(不产生任何 handler)
BasicAuth 返回 nil 表示闸没装上 —— Mount 里的 withAuth 会跳过这一层中间件,
路由照挂(但不鉴权)。
注意事项
⚠️
doc.json里是全量接口清单(路径 / 方法 / 每个接口的 RBAC 权限码) —— 必须默认带鉴权,否则等于把攻击面画好送出去。mode=none只允许本地开发。⚠️
mode=basic却没配凭据 ⇒ 直接拒绝启动(fail-fast)。config.SwaggerConfig.ResolveAuth()返回 error,cmd/server在 logger 初始化之前就panic掉了(所以是 panic 而不是log.Fatal)。 理由写在源码注释里:"mode=basic 却没配凭据,是'以为有鉴权其实没有'的典型形态: 服务能起、能访问、文档也在,但谁都能看" —— 这种洞必须在启动时就炸掉。 (router.go 里那层"解析失败就跳过挂载"是第二道防线,生产路径上走不到, 因为 main 先 panic 了。)⚠️
mode=auto没配凭据 ⇒ 本次启动随机生成一个密码并打进启动日志。 密码是 24 位十六进制(crypto/rand),重启就变。 生产环境请配固定凭据或走环境变量。 两种情况启动时都会出声:随机密码打 WARN(带密码),mode=none打 WARN("swagger 文档端点未鉴权(/swagger 全公开,含全量接口清单)")。⚠️ 改了 handler 的 DTO 之后要重跑生成器:
go run ./cmd/gen-swagger-schema。生成物落在internal/api/handler/v1/swagger_dto_gen.go,里面是"路由 handler 方法 → 请求体 DTO" 的注册表 + 字段说明表。手写一份注册表就是第二份真相:handler 里把service.CreateUserRequest换成别的类型,那张表不会跟着变, 而且不会报错,只会让文档里的字段悄悄对不上实际接口。 漂移由cmd/gen-swagger-schema/main_test.go盯着(重跑一遍逐字比)。⚠️ 覆盖率数字写在文档里:
x-schema-coverage实测routes=183/write_routes=125/with_request_schema=104/percent=83。 拿不到字段级 schema 的写接口保留空 object,不猜、不编 —— 取不到的原因会反映在这个数字里。⚠️
SetSchemaSource的 key 必须与运行期逐字对齐。HandlerKey把 hertz 的 handler 全名rapid-admin/internal/api/handler/v1.(*UserHandler).Create-fm取成(*UserHandler).Create,与生成物里的 key 对齐。 对不上不会报错,只会让那条路由的 schema 静默消失。⚠️ 必填性只认显式标签(
validate:"required"/binding:"required")。 本仓 DTO 大多没有这两个标签,只有 json tag —— 而"没有 omitempty" 并不等于"必填"。猜错的后果很具体:Swagger UI 会拦着不让提交没填的必填字段。 宁可少标必填(服务端会返回明确报错),也不要多标。⚠️ ID 字段以字符串上 wire。
jsonid.ID的 Kind 是Uint64, 但它实现了json.Marshaler—— 渲染器里"数字 + 自定义 MarshalJSON ⇒ string" 这条判定必须放在 kind 分支之前,否则先走整数分支就返回了,jsonid.ID会被写成 integer,而 wire 上其实是字符串 (sonyflake 是 19 位数,JS 的 2^53 装不下)。⚠️ 静态资产路径必须过
fs.ValidPath—— 它拒绝../.段和绝对路径。 没有这道闸,GET /swagger/../../etc/passwd就能读到文件系统别的东西。 (embed.FS 自己也会挡一部分,但那是"碰巧",不能当成防线。)⚠️
.js必须是application/javascript—— swagger-ui 靠<script src>加载。 服务端返text/plain会被浏览器拒绝执行(控制台报 MIME 错),页面一片空白。⚠️
assets传nil时只挂doc.json,UI 页面 404。UI 资产由调用方提供 —— 本包不内置 swagger-ui(那是一份 ~4MB 的第三方产物, 塞进internal/pkg会让这个"框架原语"背上一个没法审计的依赖)。 仓库里那份在server/swagger/ui/(swagger-ui 5.10.5,Apache-2.0, 许可证全文随资产收在同目录)。⚠️ 401 必须带
WWW-Authenticate头,否则浏览器只显示一个空的 401 页面, 用户完全不知道要登录。⚠️ 密码里带冒号是允许的 —— 统一按第一个冒号切:前面是用户名, 其余全是密码。按最后一个冒号切就反了(
"a:b:c"会变成 用户"a:b"/ 密码"c")。⚠️
Mount幂等:同一个 Hertz 实例只挂一次路由;换个实例(单测场景)会再挂一份。 鉴权结论由ResolveAuth()解析 —— 它是幂等的,main.go 先调一次做 fail-fast、 router 里再调一次拿结论,两次不会打架(否则日志里印的密码跟真正生效的不是同一个)。⚠️ 比较必须用
subtle.ConstantTimeCompare—— 普通字符串比较会在 第一个不同的字节上短路,理论上可被计时攻击逐字节爆破出密码。 用户名和密码都要比:只比密码的话,用户名就成了可以随便猜的公开信息。