feat: add gen api @doc comment to logic handler routes (#3790)

Co-authored-by: Kevin Wan <wanjunfeng@gmail.com>

tools/goctl/api/gogen/genhandlers.go

@@ -18,19 +18,6 @@ const defaultLogicPackage = "logic"
 //go:embed handler.tpl
 var handlerTemplate string
 
-type handlerInfo struct {
-	PkgName            string
-	ImportPackages     string
-	ImportHttpxPackage string
-	HandlerName        string
-	RequestType        string
-	LogicName          string
-	LogicType          string
-	Call               string
-	HasResp            bool
-	HasRequest         bool
-}
-
 func genHandler(dir, rootPkg string, cfg *config.Config, group spec.Group, route spec.Route) error {
 	handler := getHandlerName(route)
 	handlerPath := getHandlerFolderPath(group, route)
@@ -40,23 +27,6 @@ func genHandler(dir, rootPkg string, cfg *config.Config, group spec.Group, route
 		handler = strings.Title(handler)
 		logicName = pkgName
 	}
-
-	return doGenToFile(dir, handler, cfg, group, route, handlerInfo{
-		PkgName:        pkgName,
-		ImportPackages: genHandlerImports(group, route, rootPkg),
-		HandlerName:    handler,
-		RequestType:    util.Title(route.RequestTypeName()),
-		LogicName:      logicName,
-		LogicType:      strings.Title(getLogicName(route)),
-		Call:           strings.Title(strings.TrimSuffix(handler, "Handler")),
-		HasResp:        len(route.ResponseTypeName()) > 0,
-		HasRequest:     len(route.RequestTypeName()) > 0,
-	})
-}
-
-func doGenToFile(dir, handler string, cfg *config.Config, group spec.Group,
-	route spec.Route, handleObj handlerInfo,
-) error {
 	filename, err := format.FileNamingFormat(cfg.NamingFormat, handler)
 	if err != nil {
 		return err
@@ -70,7 +40,19 @@ func doGenToFile(dir, handler string, cfg *config.Config, group spec.Group,
 		category:        category,
 		templateFile:    handlerTemplateFile,
 		builtinTemplate: handlerTemplate,
-		data:            handleObj,
+		data: map[string]any{
+			"PkgName":        pkgName,
+			"ImportPackages": genHandlerImports(group, route, rootPkg),
+			"HandlerName":    handler,
+			"RequestType":    util.Title(route.RequestTypeName()),
+			"LogicName":      logicName,
+			"LogicType":      strings.Title(getLogicName(route)),
+			"Call":           strings.Title(strings.TrimSuffix(handler, "Handler")),
+			"HasResp":        len(route.ResponseTypeName()) > 0,
+			"HasRequest":     len(route.RequestTypeName()) > 0,
+			"HasDoc":         len(route.JoinedDoc()) > 0,
+			"Doc":            getDoc(route.JoinedDoc()),
+		},
 	})
 }
 

tools/goctl/api/gogen/genlogic.go

@@ -62,7 +62,7 @@ func genLogicByRoute(dir, rootPkg string, cfg *config.Config, group spec.Group,
 		category:        category,
 		templateFile:    logicTemplateFile,
 		builtinTemplate: logicTemplate,
-		data: map[string]string{
+		data: map[string]any{
 			"pkgName":      subDir[strings.LastIndex(subDir, "/")+1:],
 			"imports":      imports,
 			"logic":        strings.Title(logic),
@@ -70,6 +70,8 @@ func genLogicByRoute(dir, rootPkg string, cfg *config.Config, group spec.Group,
 			"responseType": responseString,
 			"returnString": returnString,
 			"request":      requestString,
+			"hasDoc":       len(route.JoinedDoc()) > 0,
+			"doc":          getDoc(route.JoinedDoc()),
 		},
 	})
 }

tools/goctl/api/gogen/genroutes.go

@@ -71,6 +71,7 @@ type (
 		method  string
 		path    string
 		handler string
+		doc     string
 	}
 )
 
@@ -92,13 +93,24 @@ func genRoutes(dir, rootPkg string, cfg *config.Config, api *spec.ApiSpec) error
 		var gbuilder strings.Builder
 		gbuilder.WriteString("[]rest.Route{")
 		for _, r := range g.routes {
-			fmt.Fprintf(&gbuilder, `
-		{
-			Method:  %s,
-			Path:    "%s",
-			Handler: %s,
-		},`,
-				r.method, r.path, r.handler)
+			var routeString string
+			if len(r.doc) > 0 {
+				routeString = fmt.Sprintf(`
+					{
+						%s
+						Method:  %s,
+						Path:    "%s",
+						Handler: %s,
+					},`, getDoc(r.doc), r.method, r.path, r.handler)
+			} else {
+				routeString = fmt.Sprintf(`
+					{
+						Method:  %s,
+						Path:    "%s",
+						Handler: %s,
+					},`, r.method, r.path, r.handler)
+			}
+			fmt.Fprint(&gbuilder, routeString)
 		}
 
 		var jwt string
@@ -239,6 +251,7 @@ func getRoutes(api *spec.ApiSpec) ([]group, error) {
 				method:  mapping[r.Method],
 				path:    r.Path,
 				handler: handler,
+				doc:     r.JoinedDoc(),
 			})
 		}
 

tools/goctl/api/gogen/handler.tpl

@@ -7,6 +7,7 @@ import (
 	{{.ImportPackages}}
 )
 
+{{if .HasDoc}}{{.Doc}}{{end}}
 func {{.HandlerName}}(svcCtx *svc.ServiceContext) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		{{if .HasRequest}}var req types.{{.RequestType}}

tools/goctl/api/gogen/logic.tpl

@@ -10,6 +10,7 @@ type {{.logic}} struct {
 	svcCtx *svc.ServiceContext
 }
 
+{{if .hasDoc}}{{.doc}}{{end}}
 func New{{.logic}}(ctx context.Context, svcCtx *svc.ServiceContext) *{{.logic}} {
 	return &{{.logic}}{
 		Logger: logx.WithContext(ctx),

tools/goctl/api/gogen/testdata/has_comment_api_test.api

@@ -16,5 +16,11 @@ service A-api {
     @server(
         handler: GreetHandler
     )
-    get /greet/from/:name(Request) returns (Response)
-}
+    get /greet/from/:name (Request) returns (Response)
+
+    @doc(
+        summary: "comment comment comment"
+    )
+    @handler NoResponseHandler
+    get /greet/get (Request)
+}

tools/goctl/api/gogen/util.go

@@ -181,3 +181,11 @@ func golangExpr(ty spec.Type, pkg ...string) string {
 
 	return ""
 }
+
+func getDoc(doc string) string {
+	if len(doc) == 0 {
+		return ""
+	}
+
+	return "// " + strings.Trim(doc, "\"")
+}