如何在Go Fiber Router函数内为各路由声明Swagger文档注释？

问题原因 #

swag工具默认只会扫描顶层函数、结构体等全局声明上方的注释，不会解析函数内部的注释。你在DeviceRoute函数内部为每个路由添加的注释，完全不在swag的扫描范围内，所以生成的Swagger文档中没有任何接口定义，出现No operations defined in spec!的提示。

解决方案 #

这里提供两种常用的正确做法：

方法1：将注释移到对应的控制器函数上方（推荐）

这是Swagger文档生成的标准实践，把每个接口的注释直接写在处理该请求的控制器函数顶部，swag会自动扫描这些顶层函数的注释并生成文档。

示例：
控制器文件（controllers/devices.go）

// GetDevices godoc
// @Summary Get all Devices
// @ID get-all-devices
// @Description Get all Devices
// @Accept json
// @Produce json
// @Tags Devices End Points
// @Success 200 {object} models.Device
// @Failure 400 {object} utils.HTTPError
// @Failure 404 {object} utils.HTTPError
// @Failure 500 {object} utils.HTTPError
// @Router /api/devices/ [get]
func GetDevices(c *fiber.Ctx) error {
    // 你的业务逻辑
    return c.JSON(models.Device{ID: 1, Name: "Test Device"})
}

// CreateDevice godoc
// @Summary Create a device
// @ID create-device
// @Description Create a device with given details
// @Accept json
// @Produce json
// @Tags Devices End Points
// @Param device body models.Device true "Device details to create"
// @Success 200 {object} models.Device
// @Failure 400 {object} utils.HTTPError
// @Failure 404 {object} utils.HTTPError
// @Failure 500 {object} utils.HTTPError
// @Router /api/devices/create [post]
func CreateDevice(c *fiber.Ctx) error {
    var device models.Device
    if err := c.BodyParser(&device); err != nil {
        return c.Status(fiber.StatusBadRequest).JSON(utils.HTTPError{Code: 400, Message: "Invalid request body"})
    }
    // 保存设备逻辑
    return c.JSON(device)
}

路由分组文件（routes/devices.go）

func DeviceRoute(route fiber.Router) {
    route.Get("", controllers.GetDevices)
    route.Post("/create", services.CheckMiddleware, controllers.CreateDevice)
}

方法2：使用Swagger的路由注释扩展（适用于必须在路由层管理注释的场景）

如果你坚持要在路由分组函数中管理注释，可以通过修改swag init的扫描参数，让它尝试识别函数内部的注释，但这种方式不推荐，因为会增加扫描复杂度。步骤如下：

1. 确保你的注释紧挨着路由注册语句（比如route.Get）的上方，不要留空行。
2. 执行扫描命令时添加--parseInternal参数：

swag init --parseInternal

注意：这种方式可能存在兼容性问题，swag对内部注释的解析支持不如顶层函数完善，所以优先推荐方法1。

额外注意事项 #

• 你的原始代码中第一个路由的注释里重复了@ID get-item-by-int，这会导致Swagger文档的ID冲突，即使注释被扫描到也会引发错误，需要删除重复的@ID字段。
• 确保@Router中的路径与实际路由路径完全一致，包括前缀（比如/api/devices/和/api/devices/create）。

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