feature/goctl-api-swagger (#4780)

Author: kesonan

tools/goctl/api/cmd.go

@@ -10,10 +10,12 @@ import (
 	"github.com/zeromicro/go-zero/tools/goctl/api/javagen"
 	"github.com/zeromicro/go-zero/tools/goctl/api/ktgen"
 	"github.com/zeromicro/go-zero/tools/goctl/api/new"
+	"github.com/zeromicro/go-zero/tools/goctl/api/swagger"
 	"github.com/zeromicro/go-zero/tools/goctl/api/tsgen"
 	"github.com/zeromicro/go-zero/tools/goctl/api/validate"
 	"github.com/zeromicro/go-zero/tools/goctl/config"
 	"github.com/zeromicro/go-zero/tools/goctl/internal/cobrax"
+	"github.com/zeromicro/go-zero/tools/goctl/pkg/env"
 	"github.com/zeromicro/go-zero/tools/goctl/plugin"
 )
 
@@ -31,6 +33,7 @@ var (
 	ktCmd       = cobrax.NewCommand("kt", cobrax.WithRunE(ktgen.KtCommand))
 	pluginCmd   = cobrax.NewCommand("plugin", cobrax.WithRunE(plugin.PluginCommand))
 	tsCmd       = cobrax.NewCommand("ts", cobrax.WithRunE(tsgen.TsCommand))
+	swaggerCmd  = cobrax.NewCommand("swagger", cobrax.WithRunE(swagger.Command))
 )
 
 func init() {
@@ -46,6 +49,7 @@ func init() {
 		pluginCmdFlags   = pluginCmd.Flags()
 		tsCmdFlags       = tsCmd.Flags()
 		validateCmdFlags = validateCmd.Flags()
+		swaggerCmdFlags  = swaggerCmd.Flags()
 	)
 
 	apiCmdFlags.StringVar(&apigen.VarStringOutput, "o")
@@ -97,8 +101,15 @@ func init() {
 	tsCmdFlags.StringVar(&tsgen.VarStringCaller, "caller")
 	tsCmdFlags.BoolVar(&tsgen.VarBoolUnWrap, "unwrap")
 
+	swaggerCmdFlags.StringVar(&swagger.VarStringAPI, "api")
+	swaggerCmdFlags.StringVar(&swagger.VarStringDir, "dir")
+	swaggerCmdFlags.BoolVar(&swagger.VarBoolYaml, "yaml")
+
 	validateCmdFlags.StringVar(&validate.VarStringAPI, "api")
 
 	// Add sub-commands
 	Cmd.AddCommand(dartCmd, docCmd, formatCmd, goCmd, javaCmd, ktCmd, newCmd, pluginCmd, tsCmd, validateCmd)
+	if env.UseExperimental() {
+		Cmd.AddCommand(swaggerCmd)
+	}
 }

tools/goctl/api/spec/spec.go

@@ -21,7 +21,7 @@ type (
 
 	// ApiSpec describes an api file
 	ApiSpec struct {
-		Info    Info      // Deprecated: useless expression
+		Info    Info
 		Syntax  ApiSyntax // Deprecated: useless expression
 		Imports []Import  // Deprecated: useless expression
 		Types   []Type

tools/goctl/api/swagger/annotation.go

@@ -0,0 +1,62 @@
+package swagger
+
+import (
+	"strconv"
+
+	"github.com/zeromicro/go-zero/tools/goctl/util"
+	"google.golang.org/grpc/metadata"
+)
+
+func getBoolFromKVOrDefault(properties map[string]string, key string, def bool) bool {
+	if len(properties) == 0 {
+		return def
+	}
+	md := metadata.New(properties)
+	val := md.Get(key)
+	if len(val) == 0 {
+		return def
+	}
+	str := util.Unquote(val[0])
+	if len(str) == 0 {
+		return def
+	}
+	res, _ := strconv.ParseBool(str)
+	return res
+}
+
+func getStringFromKVOrDefault(properties map[string]string, key string, def string) string {
+	if len(properties) == 0 {
+		return def
+	}
+	md := metadata.New(properties)
+	val := md.Get(key)
+	if len(val) == 0 {
+		return def
+	}
+	str := util.Unquote(val[0])
+	if len(str) == 0 {
+		return def
+	}
+	return str
+}
+
+func getListFromInfoOrDefault(properties map[string]string, key string, def []string) []string {
+	if len(properties) == 0 {
+		return def
+	}
+	md := metadata.New(properties)
+	val := md.Get(key)
+	if len(val) == 0 {
+		return def
+	}
+
+	str := util.Unquote(val[0])
+	if len(str) == 0 {
+		return def
+	}
+	resp := util.FieldsAndTrimSpace(str, commaRune)
+	if len(resp) == 0 {
+		return def
+	}
+	return resp
+}

tools/goctl/api/swagger/annotation_test.go

@@ -0,0 +1,53 @@
+package swagger
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_getBoolFromKVOrDefault(t *testing.T) {
+	properties := map[string]string{
+		"enabled":     `"true"`,
+		"disabled":    `"false"`,
+		"invalid":     `"notabool"`,
+		"empty_value": `""`,
+	}
+
+	assert.True(t, getBoolFromKVOrDefault(properties, "enabled", false))
+	assert.False(t, getBoolFromKVOrDefault(properties, "disabled", true))
+	assert.False(t, getBoolFromKVOrDefault(properties, "invalid", false))
+	assert.True(t, getBoolFromKVOrDefault(properties, "missing", true))
+	assert.False(t, getBoolFromKVOrDefault(properties, "empty_value", false))
+	assert.False(t, getBoolFromKVOrDefault(nil, "nil", false))
+	assert.False(t, getBoolFromKVOrDefault(map[string]string{}, "empty", false))
+}
+
+func Test_getStringFromKVOrDefault(t *testing.T) {
+	properties := map[string]string{
+		"name":  `"example"`,
+		"empty": `""`,
+	}
+
+	assert.Equal(t, "example", getStringFromKVOrDefault(properties, "name", "default"))
+	assert.Equal(t, "default", getStringFromKVOrDefault(properties, "empty", "default"))
+	assert.Equal(t, "default", getStringFromKVOrDefault(properties, "missing", "default"))
+	assert.Equal(t, "default", getStringFromKVOrDefault(nil, "nil", "default"))
+	assert.Equal(t, "default", getStringFromKVOrDefault(map[string]string{}, "empty", "default"))
+}
+
+func Test_getListFromInfoOrDefault(t *testing.T) {
+	properties := map[string]string{
+		"list":  `"a, b, c"`,
+		"empty": `""`,
+	}
+
+	assert.Equal(t, []string{"a", "b", "c"}, getListFromInfoOrDefault(properties, "list", []string{"default"}))
+	assert.Equal(t, []string{"default"}, getListFromInfoOrDefault(properties, "empty", []string{"default"}))
+	assert.Equal(t, []string{"default"}, getListFromInfoOrDefault(properties, "missing", []string{"default"}))
+	assert.Equal(t, []string{"default"}, getListFromInfoOrDefault(nil, "nil", []string{"default"}))
+	assert.Equal(t, []string{"default"}, getListFromInfoOrDefault(map[string]string{}, "empty", []string{"default"}))
+	assert.Equal(t, []string{"default"}, getListFromInfoOrDefault(map[string]string{
+		"foo": ",,",
+	}, "foo", []string{"default"}))
+}

tools/goctl/api/swagger/api.go

@@ -0,0 +1,138 @@
+package swagger
+
+import "github.com/zeromicro/go-zero/tools/goctl/api/spec"
+
+func fillAllStructs(api *spec.ApiSpec) {
+	var (
+		tps         []spec.Type
+		structTypes = make(map[string]spec.DefineStruct)
+		groups      []spec.Group
+	)
+	for _, tp := range api.Types {
+		structTypes[tp.Name()] = tp.(spec.DefineStruct)
+	}
+
+	for _, tp := range api.Types {
+		filledTP := fillStruct("", tp, structTypes)
+		tps = append(tps, filledTP)
+		structTypes[filledTP.Name()] = filledTP.(spec.DefineStruct)
+	}
+
+	for _, group := range api.Service.Groups {
+		var routes []spec.Route
+		for _, route := range group.Routes {
+			route.RequestType = fillStruct("", route.RequestType, structTypes)
+			route.ResponseType = fillStruct("", route.ResponseType, structTypes)
+			routes = append(routes, route)
+		}
+		group.Routes = routes
+		groups = append(groups, group)
+	}
+	api.Service.Groups = groups
+	api.Types = tps
+}
+
+func fillStruct(parent string, tp spec.Type, allTypes map[string]spec.DefineStruct) spec.Type {
+	switch val := tp.(type) {
+	case spec.DefineStruct:
+		var members []spec.Member
+		for _, member := range val.Members {
+			switch memberType := member.Type.(type) {
+			case spec.PointerType:
+				member.Type = spec.PointerType{
+					RawName: memberType.RawName,
+					Type:    fillStruct(val.Name(), memberType.Type, allTypes),
+				}
+			case spec.ArrayType:
+				member.Type = spec.ArrayType{
+					RawName: memberType.RawName,
+					Value:   fillStruct(val.Name(), memberType.Value, allTypes),
+				}
+			case spec.MapType:
+				member.Type = spec.MapType{
+					RawName: memberType.RawName,
+					Key:     memberType.Key,
+					Value:   fillStruct(val.Name(), memberType.Value, allTypes),
+				}
+			case spec.DefineStruct:
+				if parent != memberType.Name() { // avoid recursive struct
+					if st, ok := allTypes[memberType.Name()]; ok {
+						member.Type = fillStruct("", st, allTypes)
+					}
+				}
+			case spec.NestedStruct:
+				member.Type = fillStruct("", member.Type, allTypes)
+			}
+			members = append(members, member)
+		}
+		if len(members) == 0 {
+			st, ok := allTypes[val.RawName]
+			if ok {
+				members = st.Members
+			}
+		}
+		val.Members = members
+		return val
+	case spec.NestedStruct:
+		var members []spec.Member
+		for _, member := range val.Members {
+			switch memberType := member.Type.(type) {
+			case spec.PointerType:
+				member.Type = spec.PointerType{
+					RawName: memberType.RawName,
+					Type:    fillStruct(val.Name(), memberType.Type, allTypes),
+				}
+			case spec.ArrayType:
+				member.Type = spec.ArrayType{
+					RawName: memberType.RawName,
+					Value:   fillStruct(val.Name(), memberType.Value, allTypes),
+				}
+			case spec.MapType:
+				member.Type = spec.MapType{
+					RawName: memberType.RawName,
+					Key:     memberType.Key,
+					Value:   fillStruct(val.Name(), memberType.Value, allTypes),
+				}
+			case spec.DefineStruct:
+				if parent != memberType.Name() { // avoid recursive struct
+					if st, ok := allTypes[memberType.Name()]; ok {
+						member.Type = fillStruct("", st, allTypes)
+					}
+				}
+			case spec.NestedStruct:
+				if parent != memberType.Name() {
+					if st, ok := allTypes[memberType.Name()]; ok {
+						member.Type = fillStruct("", st, allTypes)
+					}
+				}
+			}
+			members = append(members, member)
+		}
+		if len(members) == 0 {
+			st, ok := allTypes[val.RawName]
+			if ok {
+				members = st.Members
+			}
+		}
+		val.Members = members
+		return val
+	case spec.PointerType:
+		return spec.PointerType{
+			RawName: val.RawName,
+			Type:    fillStruct(parent, val.Type, allTypes),
+		}
+	case spec.ArrayType:
+		return spec.ArrayType{
+			RawName: val.RawName,
+			Value:   fillStruct(parent, val.Value, allTypes),
+		}
+	case spec.MapType:
+		return spec.MapType{
+			RawName: val.RawName,
+			Key:     val.Key,
+			Value:   fillStruct(parent, val.Value, allTypes),
+		}
+	default:
+		return tp
+	}
+}

tools/goctl/api/swagger/command.go

@@ -0,0 +1,79 @@
+package swagger
+
+import (
+	"encoding/json"
+	"errors"
+	"github.com/zeromicro/go-zero/tools/goctl/util/pathx"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/zeromicro/go-zero/tools/goctl/pkg/parser/api/parser"
+	"gopkg.in/yaml.v2"
+)
+
+var (
+	// VarStringAPI specifies the API filename.
+	VarStringAPI string
+
+	// VarStringDir specifies the directory to generate swagger file.
+	VarStringDir string
+
+	// VarBoolYaml specifies whether to generate a YAML file.
+	VarBoolYaml bool
+)
+
+func Command(_ *cobra.Command, _ []string) error {
+	if len(VarStringAPI) == 0 {
+		return errors.New("missing -api")
+	}
+
+	if len(VarStringDir) == 0 {
+		return errors.New("missing -dir")
+	}
+
+	api, err := parser.Parse(VarStringAPI, "")
+	if err != nil {
+		return err
+	}
+
+	fillAllStructs(api)
+
+	if err := api.Validate(); err != nil {
+		return err
+	}
+	swagger, err := spec2Swagger(api)
+	if err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(swagger, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	err = pathx.MkdirIfNotExist(VarStringDir)
+	if err != nil {
+		return err
+	}
+
+	base := filepath.Base(VarStringAPI)
+	if VarBoolYaml {
+		filename := filepath.Join(VarStringDir, strings.TrimSuffix(base, filepath.Ext(base))+".yaml")
+
+		var jsonObj interface{}
+		if err := yaml.Unmarshal(data, &jsonObj); err != nil {
+			return err
+		}
+
+		data, err := yaml.Marshal(jsonObj)
+		if err != nil {
+			return err
+		}
+		return os.WriteFile(filename, data, 0644)
+	}
+	// generate json swagger file
+	filename := filepath.Join(VarStringDir, strings.TrimSuffix(base, filepath.Ext(base))+".json")
+
+	return os.WriteFile(filename, data, 0644)
+}