Golang项目中如何排除未挂载到路由的Swagger接口文档？

问题原因 #

你的推测是正确的，go-swagger生成文档的逻辑是扫描指定包路径下所有带swagger:operation注解的函数，和业务代码里是否实际挂载路由没有关联，所以哪怕你没有调用AttachHealthRoutes，只要同包下的getHealthHandler带了对应的swagger注解，就会被扫描进生成的规范文件中，最终在Swagger UI展示。

可行解决方案（均无需拆分包） #

方案1：生成时排除指定Operation（最便捷，无需修改业务代码） #

你可以在执行swagger生成命令时，通过--exclude参数直接过滤掉不需要的接口：

1. 先确认getHealthHandler对应的swagger:operation定义里的ID，比如注解为// swagger:operation GET /health Health，那Operation ID就是Health
2. 生成spec时添加排除参数即可：

swagger generate spec -o ./swagger.json --exclude operation:Health

如果有多个要排除的接口，多次叠加--exclude operation:xxx参数即可。

方案2：用构建标签控制扫描范围（适合多服务差异化生成场景） #

如果部分微服务需要挂载健康检查接口、部分不需要，可以通过Go的构建标签控制生成swagger时的扫描范围：

1. 将getHealthHandler定义、对应的swagger注解、AttachHealthRoutes函数都单独放到同一个文件中，比如命名为health_routes.go
2. 在该文件最顶部添加构建标签：

//go:build include_health
// +build include_health

package othercontroller

// 后续健康检查相关代码...

3. 不需要生成健康检查接口的服务，直接执行默认生成命令即可，该文件会被自动跳过：

swagger generate spec -o ./swagger.json

需要生成健康检查接口的服务，生成时指定启用对应标签：

GOFLAGS="-tags=include_health" swagger generate spec -o ./swagger.json

方案3：运行时过滤Swagger规范（适合不想调整生成逻辑的场景） #

如果你不想修改生成命令，也可以在服务返回Swagger规范给前端之前，代码层面过滤掉不需要的路径：

import "encoding/json"

// 读取生成的swagger原始文件
rawSpec, _ := os.ReadFile("./swagger.json")
var spec map[string]interface{}
_ = json.Unmarshal(rawSpec, &spec)

// 删除paths下不需要展示的接口
paths := spec["paths"].(map[string]interface{})
delete(paths, "/health")

// 把处理后的spec返回给Swagger UI即可

内容的提问来源于stack exchange，提问作者Vallabh Lakade