feat: add openapi

internal/controllers/env_controller.go

@@ -17,6 +17,17 @@ func NewEnvController(envService *services.EnvService) *EnvController {
 	return &EnvController{envService: envService}
 }
 
+// CreateEnvVar 创建环境变量
+// @Summary 创建环境变量
+// @Description 创建新的环境变量
+// @Tags 环境变量
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Param body body object true "环境变量信息"
+// @Success 200 {object} utils.Response{data=vo.EnvVO}
+// @Failure 400 {object} utils.Response
+// @Router /env [post]
 func (ec *EnvController) CreateEnvVar(c *gin.Context) {
 	userID := c.GetString("userID")
 
@@ -41,6 +52,18 @@ func (ec *EnvController) CreateEnvVar(c *gin.Context) {
 	utils.Success(c, vo.ToEnvVO(envVar))
 }
 
+// GetEnvVars 获取环境变量列表
+// @Summary 获取环境变量列表
+// @Description 分页获取环境变量列表，支持按名称筛选
+// @Tags 环境变量
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Param name query string false "按名称模糊查询"
+// @Param page query int false "页码"
+// @Param page_size query int false "每页数量"
+// @Success 200 {object} utils.Response{data=utils.PaginationData{list=[]vo.EnvVO}}
+// @Router /env [get]
 func (ec *EnvController) GetEnvVars(c *gin.Context) {
 	userID := c.GetString("userID")
 	p := utils.ParsePagination(c)
@@ -49,12 +72,32 @@ func (ec *EnvController) GetEnvVars(c *gin.Context) {
 	utils.PaginatedResponse(c, vo.ToEnvVOListFromModels(envVars), total, p)
 }
 
+// GetAllEnvVars 获取所有环境变量
+// @Summary 获取所有环境变量
+// @Description 获取当前用户的所有环境变量（不分页）
+// @Tags 环境变量
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Success 200 {object} utils.Response{data=[]vo.EnvVO}
+// @Router /env/all [get]
 func (ec *EnvController) GetAllEnvVars(c *gin.Context) {
 	userID := c.GetString("userID")
 	envVars := ec.envService.GetEnvVarsByUserID(userID)
 	utils.Success(c, vo.ToEnvVOListFromModels(envVars))
 }
 
+// GetEnvVar 获取环境变量详情
+// @Summary 获取环境变量详情
+// @Description 根据 ID 获取环境变量详情
+// @Tags 环境变量
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Param id path string true "环境变量ID"
+// @Success 200 {object} utils.Response{data=vo.EnvVO}
+// @Failure 404 {object} utils.Response
+// @Router /env/{id} [get]
 func (ec *EnvController) GetEnvVar(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -71,6 +114,18 @@ func (ec *EnvController) GetEnvVar(c *gin.Context) {
 	utils.Success(c, vo.ToEnvVO(envVar))
 }
 
+// UpdateEnvVar 更新环境变量
+// @Summary 更新环境变量
+// @Description 根据 ID 更新环境变量信息
+// @Tags 环境变量
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Param id path string true "环境变量ID"
+// @Param body body object true "更新信息"
+// @Success 200 {object} utils.Response{data=vo.EnvVO}
+// @Failure 404 {object} utils.Response
+// @Router /env/{id} [put]
 func (ec *EnvController) UpdateEnvVar(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -110,6 +165,18 @@ func (ec *EnvController) UpdateEnvVar(c *gin.Context) {
 	utils.Success(c, vo.ToEnvVO(envVar))
 }
 
+// DeleteEnvVar 删除环境变量
+// @Summary 删除环境变量
+// @Description 根据 ID 删除环境变量，支持强制删除
+// @Tags 环境变量
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Param id path string true "环境变量ID"
+// @Param force query bool false "是否强制删除"
+// @Success 200 {object} utils.Response
+// @Failure 409 {object} utils.Response{data=[]vo.TaskVO} "引用冲突"
+// @Router /env/{id} [delete]
 func (ec *EnvController) DeleteEnvVar(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -137,6 +204,16 @@ func (ec *EnvController) DeleteEnvVar(c *gin.Context) {
 	utils.SuccessMsg(c, "删除成功")
 }
 
+// GetAssociatedTasks 获取关联任务
+// @Summary 获取关联任务
+// @Description 获取引用了该环境变量的任务列表
+// @Tags 环境变量
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Param id path string true "环境变量ID"
+// @Success 200 {object} utils.Response{data=[]vo.TaskVO}
+// @Router /env/{id}/tasks [get]
 func (ec *EnvController) GetAssociatedTasks(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {