feat: add gen api @doc comment to logic handler routes

zeromicro · Dec 15, 2023 · b6e5ff8 · b6e5ff8
1 parent d687304
commit b6e5ff8
Show file tree

Hide file tree

Showing 7 changed files with 60 additions and 47 deletions.
diff --git a/tools/goctl/api/gogen/genhandlers.go b/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()),
+		},
 	})
 }
 

diff --git a/tools/goctl/api/gogen/genlogic.go b/tools/goctl/api/gogen/genlogic.go
@@ -62,14 +62,16 @@ 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),
 			"function":     strings.Title(strings.TrimSuffix(logic, "Logic")),
 			"responseType": responseString,
 			"returnString": returnString,
 			"request":      requestString,
+			"hasDoc":       len(route.JoinedDoc()) > 0,
+			"doc":          getDoc(route.JoinedDoc()),
 		},
 	})
 }

diff --git a/tools/goctl/api/gogen/genroutes.go b/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(),
 			})
 		}
 

diff --git a/tools/goctl/api/gogen/handler.tpl b/tools/goctl/api/gogen/handler.tpl
@@ -1,26 +1,27 @@
-package {{.PkgName}}
+package {{.pkgName}}
 
 import (
 	"net/http"
 
 	"github.com/zeromicro/go-zero/rest/httpx"
-	{{.ImportPackages}}
+	{{.importPackages}}
 )
 
-func {{.HandlerName}}(svcCtx *svc.ServiceContext) http.HandlerFunc {
+{{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}}
+		{{if .hasRequest}}var req types.{{.requestType}}
 		if err := httpx.Parse(r, &req); err != nil {
 			httpx.ErrorCtx(r.Context(), w, err)
 			return
 		}
 
-		{{end}}l := {{.LogicName}}.New{{.LogicType}}(r.Context(), svcCtx)
-		{{if .HasResp}}resp, {{end}}err := l.{{.Call}}({{if .HasRequest}}&req{{end}})
+		{{end}}l := {{.logicName}}.New{{.logicType}}(r.Context(), svcCtx)
+		{{if .hasResp}}resp, {{end}}err := l.{{.call}}({{if .hasRequest}}&req{{end}})
 		if err != nil {
 			httpx.ErrorCtx(r.Context(), w, err)
 		} else {
-			{{if .HasResp}}httpx.OkJsonCtx(r.Context(), w, resp){{else}}httpx.Ok(w){{end}}
+			{{if .hasResp}}httpx.OkJsonCtx(r.Context(), w, resp){{else}}httpx.Ok(w){{end}}
 		}
 	}
 }
diff --git a/tools/goctl/api/gogen/logic.tpl b/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),

diff --git a/tools/goctl/api/gogen/testdata/has_comment_api_test.api b/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)
 }
diff --git a/tools/goctl/api/gogen/util.go b/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, "\"")
+}