goctl added

tools/goctl/api/docgen/doc.go

@@ -0,0 +1,82 @@
+package docgen
+
+import (
+	"bytes"
+	"fmt"
+	"html/template"
+	"strconv"
+	"strings"
+
+	"zero/core/stringx"
+	"zero/tools/goctl/api/gogen"
+	"zero/tools/goctl/api/spec"
+	"zero/tools/goctl/api/util"
+)
+
+const (
+	markdownTemplate = `
+### {{.index}}. {{.routeComment}}
+
+1. 路由定义
+
+- Url: {{.uri}}
+- Method: {{.method}}
+- Request: {{.requestType}}
+- Response: {{.responseType}}
+
+
+2. 类型定义 
+
+{{.responseContent}}  
+
+`
+)
+
+func genDoc(api *spec.ApiSpec, dir string, filename string) error {
+	fp, _, err := util.MaybeCreateFile(dir, "", filename)
+	if err != nil {
+		return err
+	}
+	defer fp.Close()
+
+	var builder strings.Builder
+	for index, route := range api.Service.Routes {
+		routeComment, _ := util.GetAnnotationValue(route.Annotations, "doc", "summary")
+		if len(routeComment) == 0 {
+			routeComment = "N/A"
+		}
+
+		responseContent, err := responseBody(api, route)
+		if err != nil {
+			return err
+		}
+
+		t := template.Must(template.New("markdownTemplate").Parse(markdownTemplate))
+		var tmplBytes bytes.Buffer
+		err = t.Execute(&tmplBytes, map[string]string{
+			"index":           strconv.Itoa(index + 1),
+			"routeComment":    routeComment,
+			"method":          strings.ToUpper(route.Method),
+			"uri":             route.Path,
+			"requestType":     "`" + stringx.TakeOne(route.RequestType.Name, "-") + "`",
+			"responseType":    "`" + stringx.TakeOne(route.ResponseType.Name, "-") + "`",
+			"responseContent": responseContent,
+		})
+		if err != nil {
+			return err
+		}
+
+		builder.Write(tmplBytes.Bytes())
+	}
+	_, err = fp.WriteString(strings.Replace(builder.String(), """, `"`, -1))
+	return err
+}
+
+func responseBody(api *spec.ApiSpec, route spec.Route) (string, error) {
+	tps := util.GetLocalTypes(api, route)
+	value, err := gogen.BuildTypes(tps)
+	if err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("\n\n```golang\n%s\n```\n", value), nil
+}

tools/goctl/api/docgen/gen.go

@@ -0,0 +1,65 @@
+package docgen
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"zero/tools/goctl/api/parser"
+
+	"github.com/urfave/cli"
+)
+
+var docDir = "doc"
+
+func DocCommand(c *cli.Context) error {
+	dir := c.String("dir")
+	if len(dir) == 0 {
+		return errors.New("missing -dir")
+	}
+
+	files, err := filePathWalkDir(dir)
+	if err != nil {
+		return errors.New(fmt.Sprintf("dir %s not exist", dir))
+	}
+
+	err = os.RemoveAll(dir + "/" + docDir + "/")
+	if err != nil {
+		return err
+	}
+	for _, f := range files {
+		p, err := parser.NewParser(f)
+		if err != nil {
+			return errors.New(fmt.Sprintf("parse file: %s, err: %s", f, err.Error()))
+		}
+		api, err := p.Parse()
+		if err != nil {
+			return err
+		}
+		index := strings.Index(f, dir)
+		if index < 0 {
+			continue
+		}
+		dst := dir + "/" + docDir + f[index+len(dir):]
+		index = strings.LastIndex(dst, "/")
+		if index < 0 {
+			continue
+		}
+		dir := dst[:index]
+		genDoc(api, dir, strings.Replace(dst[index+1:], ".api", ".md", 1))
+	}
+	return nil
+}
+
+func filePathWalkDir(root string) ([]string, error) {
+	var files []string
+	err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if !info.IsDir() && strings.HasSuffix(path, ".api") {
+			files = append(files, path)
+		}
+		return nil
+	})
+	return files, err
+}