swagcmd

Documentation

Index

• Variables
• type ActionItem
  • func (a ActionItem) TagComments() string
• type GroupData
• type SwagDoc
  • func (d SwagDoc) GetTagInfo(name string) (spec.Tag, bool)
  • func (d SwagDoc) PrintNode(name, filter string) (err error)

Variables

var Doc2MkDown = &gcli.Command{
	Name:    "md",
	Aliases: []string{"tomd", "mkdown", "markdown"},
	Desc:    "convert swagger document file to markdown",
	Config: func(c *gcli.Command) {

	},
	Func: func(c *gcli.Command, _ []string) error {
		return errors.New("TODO")
	},
}

var DocBrowse = &gcli.Command{
	Name:    "browse",
	Aliases: []string{"cat", "see"},
	Desc:    "open browser for browse input swagger doc file",
	Config: func(c *gcli.Command) {
		c.StrOpt(&docBrowseOpts.SwagFile,
			"swagger-file", "f",
			"swagger.json",
			"the swagger document file path",
		)
		c.StrVar(&docBrowseOpts.NodeName, &gcli.CliOpt{
			Name:   "node",
			Shorts: []string{"n"},
			Desc:   "show parts of the the documents.\nallow: tags, info, paths, defs, responses",
		})
		c.StrVar(&docBrowseOpts.PathName, &gcli.CliOpt{
			Name:   "path",
			Shorts: []string{"p"},
			Desc:   "show path info of the the `documents.paths`. eg: /anything",
		})
		c.StrVar(&docBrowseOpts.Filter, &gcli.CliOpt{
			Name: "filter",
			Desc: "filter the results of path or node",
		})
	},
	Func: func(c *gcli.Command, args []string) (err error) {

		if err := loadDocFile(docBrowseOpts.SwagFile); err != nil {
			return err
		}

		if docBrowseOpts.PathName != "" {
			path := docBrowseOpts.PathName
			if pItem, ok := swagger.SwaggerProps.Paths.Paths[path]; ok {
				bts, err := json.MarshalIndent(pItem, "", "  ")
				if err != nil {
					return err
				}

				color.Success.Printf("'paths.%s' of the Document:\n", path)
				fmt.Println(string(bts))
			} else {
				return fmt.Errorf("'paths.%s' is not exist of the Document", path)
			}
		}

		if docBrowseOpts.NodeName != "" {
			return swagger.PrintNode(docBrowseOpts.NodeName, docBrowseOpts.Filter)
		}

		return errors.New("please setting --node|--path value")
	},
}

var DocGen = &gcli.Command{
	Name: "gen",
	Desc: "generate swagger doc files by package: swaggo/swag",
	Config: func(c *gcli.Command) {
		c.StrOpt(&docGenOpts.Output, "output", "o", "./static", `the output directory for generated doc files`)
	},
	Func: func(c *gcli.Command, _ []string) error {

		ret, err := sysutil.ExecCmd("swag", []string{
			"init",
			"-o",
			docGenOpts.Output,
		})
		fmt.Println(ret)

		return err
	},
	Help: `
Install swaggo:
    go get -u github.com/swaggo/swag/cmd/swag
`,
}

var GenCode = &gcli.Command{
	Name:    "swag2go",
	Aliases: []string{"swag2code"},
	Desc:    "generate go API service codes by swagger.yaml or swagger.json",
	Config: func(c *gcli.Command) {
		c.StrOpt(&swag2codeOpts.SwagFile,
			"swagger-file",
			"f",
			"api",
			"the swagger doc filepath",
		)
		c.StrOpt(&swag2codeOpts.PkgName, "pgk-name", "p", "./swagger.json", "the generated package name")
		c.StrOpt(&swag2codeOpts.OutDir,
			"output",
			"o",
			"./gocodes",
			`the output directory for generated codes
if input 'stdout' will print codes on terminal
`)
		c.StrVar(&swag2codeOpts.Template, &gcli.CliOpt{
			Name:   "template",
			Desc:   "the template name for generate codes",
			Shorts: []string{"t"},
			DefVal: "rux-controller",
		})
		c.StrVar(&swag2codeOpts.GroupType, &gcli.CliOpt{
			Name: "group-type",
			Desc: `the code generate group type. allow:
none - dont generate group struct
path - group by path name
tag  - group by tag name
`,
			DefVal: "tag",
			Validator: func(val string) error {
				ss := []string{"none", "path", "tag"}
				for _, s := range ss {
					if s == val {
						return nil
					}
				}

				return fmt.Errorf("'group-type' must one of %v", ss)
			},
		})
		c.StrVar(&swag2codeOpts.GroupSuffix, &gcli.CliOpt{
			Name:   "group-suffix",
			Desc:   "Add suffix for group name. eg: API, Controller",
			DefVal: "API",
		})
		c.StrVar(&swag2codeOpts.ActionSuffix, &gcli.CliOpt{
			Name: "action-suffix",
			Desc: "Add suffix for action name. eg: Action, Method",
		})
		c.VarOpt(&swag2codeOpts.SpecPaths, "paths", "", "only generate for the given spec paths")
		c.Examples = `
{$fullCmd} --paths /anything /blog/{id}
{$fullCmd} -f testdata/swagger.json --paths /anything/{anything} --group-type path -o stdout
`
	},
	Func: func(c *gcli.Command, args []string) (err error) {

		if err := loadDocFile(swag2codeOpts.SwagFile); err != nil {
			return err
		}

		if len(swagger.SwaggerProps.Paths.Paths) == 0 {
			return errors.New("API doc 'paths' is empty")
		}

		if err = loadAndParseTemplate(); err != nil {
			return
		}

		dump.Config(func(d *dump.Options) {
			d.MaxDepth = 8
		})

		outDir := swag2codeOpts.OutDir
		if outDir != stdoutName && fsutil.IsDir(outDir) {
			slog.Info("create the output directory:", outDir)

			err = os.MkdirAll(outDir, 0664)
			if err != nil {
				return err
			}
		}

		if len(swag2codeOpts.SpecPaths) > 0 {
			slog.Info("will only generate for the paths: ", swag2codeOpts.SpecPaths)

			for _, path := range swag2codeOpts.SpecPaths {
				if pathItem, ok := swagger.SwaggerProps.Paths.Paths[path]; ok {
					err = generateByPathItem(path, pathItem)
					if err != nil {
						return
					}
				} else {
					slog.Errorf("- the path '%s' is not exists on docs, skip gen", path)
				}
			}
		} else {
			for path, pathItem := range swagger.SwaggerProps.Paths.Paths {
				err = generateByPathItem(path, pathItem)
				if err != nil {
					return
				}
			}
		}
		return
	},
}

var InstallSwagGo = &gcli.Command{
	Name:    "swaggo",
	Aliases: []string{"swaggo-ins"},
	Desc:    "install swaggo/swag from github repository",
	Config: func(c *gcli.Command) {

	},
	Func: func(c *gcli.Command, _ []string) error {
		return errors.New("TODO")
	},
}

var SwaggerCmd = &gcli.Command{
	Name: "swag",
	Desc: "some tool for use swagger",
	Subs: []*gcli.Command{
		DocBrowse,
		DocGen,
		Doc2MkDown,
		GenCode,
		InstallSwagGo,
	},
}

SwaggerCmd instance

Types

type ActionItem

type ActionItem struct {
	// Path route path
	Path string
	Tags []string
	// METHOD the request METHOD. eg. GET
	METHOD string
	// MethodName the action method name
	MethodName string
	// MethodDesc the action method desc
	MethodDesc string
}

ActionItem struct

func (ActionItem) TagComments

func (a ActionItem) TagComments() string

TagComments line

type GroupData

type GroupData struct {
	GroupName string
	GroupDesc string
	GroupPath string

	PkgName string
	Actions []ActionItem
	TagMap  map[string]string
}

type SwagDoc

type SwagDoc struct {
	spec.Swagger
}

SwagDoc struct

func (SwagDoc) GetTagInfo

func (d SwagDoc) GetTagInfo(name string) (spec.Tag, bool)

func (SwagDoc) PrintNode

func (d SwagDoc) PrintNode(name, filter string) (err error)

PrintNode JSON string