diff --git a/tools/goctl/api/gogen/genhandlers.go b/tools/goctl/api/gogen/genhandlers.go
index fa1093ec18fc..da4131a8525e 100644
--- a/tools/goctl/api/gogen/genhandlers.go
+++ b/tools/goctl/api/gogen/genhandlers.go
@@ -27,6 +27,7 @@ type handlerInfo struct {
 	LogicName          string
 	LogicType          string
 	Call               string
+	HandlerComment     string
 	HasResp            bool
 	HasRequest         bool
 }
@@ -49,6 +50,7 @@ func genHandler(dir, rootPkg string, cfg *config.Config, group spec.Group, route
 		LogicName:      logicName,
 		LogicType:      strings.Title(getLogicName(route)),
 		Call:           strings.Title(strings.TrimSuffix(handler, "Handler")),
+		HandlerComment: getHandlerDoc(route),
 		HasResp:        len(route.ResponseTypeName()) > 0,
 		HasRequest:     len(route.RequestTypeName()) > 0,
 	})
@@ -61,6 +63,11 @@ func doGenToFile(dir, handler string, cfg *config.Config, group spec.Group,
 	if err != nil {
 		return err
 	}
+	filename = filename + ".go"
+	targetFile := path.Join(dir, getHandlerFolderPath(group, route), filename)
+	if pathx.FileExists(targetFile) {
+		return updateHandlerComments(targetFile, handler, route.HandlerDoc)
+	}
 
 	return genFile(fileGenConfig{
 		dir:             dir,
@@ -139,3 +146,8 @@ func getLogicName(route spec.Route) string {
 
 	return handler + "Logic"
 }
+
+func getHandlerDoc(route spec.Route) string {
+	doc := strings.Join(route.HandlerDoc, "\n")
+	return doc
+}
diff --git a/tools/goctl/api/gogen/handler.tpl b/tools/goctl/api/gogen/handler.tpl
index a6480a2314f4..81e4fcfaecb3 100644
--- a/tools/goctl/api/gogen/handler.tpl
+++ b/tools/goctl/api/gogen/handler.tpl
@@ -7,6 +7,7 @@ import (
 	{{.ImportPackages}}
 )
 
+{{.HandlerComment}}
 func {{.HandlerName}}(svcCtx *svc.ServiceContext) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		{{if .HasRequest}}var req types.{{.RequestType}}
diff --git a/tools/goctl/api/gogen/updatehandler.go b/tools/goctl/api/gogen/updatehandler.go
new file mode 100644
index 000000000000..280924588e91
--- /dev/null
+++ b/tools/goctl/api/gogen/updatehandler.go
@@ -0,0 +1,57 @@
+package gogen
+
+import (
+	"bytes"
+	"fmt"
+	"go/ast"
+	"go/format"
+	"go/parser"
+	"go/token"
+	"os"
+)
+
+func updateHandlerComments(filename string, handlerName string, comments []string) error {
+	// Parse the code file
+	fset := token.NewFileSet()
+	f, err := parser.ParseFile(fset, filename, nil, parser.ParseComments)
+	if err != nil {
+		return err
+	}
+
+	// Find the UserSelfHandler function
+	var fn *ast.FuncDecl
+	for i := range f.Decls {
+		if fd, ok := f.Decls[i].(*ast.FuncDecl); ok && fd.Name.Name == handlerName {
+			fn = fd
+			break
+		}
+	}
+	if fn == nil {
+		return fmt.Errorf("handler %s not found", handlerName)
+	}
+
+	// Update the function's comments
+	var list []*ast.Comment
+	for i, comment := range comments {
+		if i == 0 {
+			list = append(list, &ast.Comment{Slash: fn.Pos() - 1, Text: comment})
+		} else {
+			list = append(list, &ast.Comment{Text: comment})
+		}
+	}
+	if fn.Doc == nil {
+		fn.Doc = &ast.CommentGroup{}
+	}
+	fn.Doc.List = list
+
+	// Format and write the updated code to file
+	var buf bytes.Buffer
+	if err := format.Node(&buf, fset, f); err != nil {
+		return err
+	}
+	if err := os.WriteFile(filename, buf.Bytes(), 0644); err != nil {
+		return err
+	}
+
+	return nil
+}