Swaggo中定义带查询参数的路由？路由注释解析报错

你之前的错误在于把查询参数写进了@Router的路径里，Swaggo的@Router只需要声明基础路由路径，查询参数完全通过@Param标签来定义，不需要在路由中拼接?xxx={id}这类格式。

针对你的业务场景，分两种常见处理方式：

方式1：合并为一个接口文档（推荐，匹配你当前的代码逻辑） #

你的代码是同一个/books路由，根据是否存在查询参数分支处理，所以直接给GetAllBook添加包含可选查询参数的注释即可：

// @Summary 获取书籍列表（支持分类筛选）
// @Description 传入genre参数时按分类ID查询书籍，无参数时返回全部书籍
// @Param genre query int false "分类ID，可选参数"
// @Router /books [get]
func GetAllBook(c *gin.Context) {
    id := c.Request.URL.Query().Get("genre")
    if id != "" {
        GetAllBookByGenreId(id, c)
        return
    }
    // 获取全部书籍的逻辑代码
}

这里的false表示该查询参数是可选的，用户可以选择传或不传，Swaggo会自动在文档中生成对应的参数输入框。

方式2：拆分为两个接口文档（适合分开维护逻辑的场景） #

如果想把“查全部”和“按分类查”拆成两个独立的文档条目，只需要保持@Router路径一致，分别用@Param声明参数即可：

// @Summary 获取全部书籍
// @Description 返回系统中所有书籍数据
// @Router /books [get]
func GetAllBook(c *gin.Context) {
    // 获取全部书籍的逻辑代码
}

// @Summary 按分类ID查询书籍
// @Description 根据指定的分类ID返回对应书籍
// @Param genre query int true "分类ID，必填参数"
// @Router /books [get]
func GetAllBookByGenreId(c *gin.Context) {
    id := c.Query("genre")
    // 按分类查询书籍的逻辑代码
}

这里的true表示该查询参数是必填的，Swaggo会在文档中标记为必填项。

核心规则：Swaggo的路由路径只需要写基础路径，查询参数、路径参数（比如/books/{id}）分别通过@Param的query/path类型来声明，不要在路由路径里直接拼接参数。

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