fix x-logo vendor extension & parse x-codeSamples from files (#760)

README.md

@@ -73,15 +73,19 @@ USAGE:
    swag init [command options] [arguments...]
 
 OPTIONS:
-   --generalInfo value, -g value       Go file path in which 'swagger general API Info' is written (default: "main.go")
-   --dir value, -d value               Directory you want to parse (default: "./")
-   --exclude value                     Exclude directories and files, comma separated
-   --propertyStrategy value, -p value  Property Naming Strategy like snakecase,camelcase,pascalcase (default: "camelcase")
-   --output value, -o value            Output directory for all the generated files(swagger.json, swagger.yaml and doc.go) (default: "./docs")
-   --parseVendor                       Parse go files in 'vendor' folder, disabled by default
-   --parseDependency                   Parse go files in outside dependency folder, disabled by default
-   --parseInternal                     Parse go files in internal packages, disabled by default
-   --parseDepth                        Dependency parse depth (default: 100)
+   --generalInfo value, -g value          Go file path in which 'swagger general API Info' is written (default: "main.go")
+   --dir value, -d value                  Directory you want to parse (default: "./")
+   --exclude value                        Exclude directories and files, comma separated
+   --propertyStrategy value, -p value     Property Naming Strategy like snakecase,camelcase,pascalcase (default: "camelcase")
+   --output value, -o value               Output directory for all the generated files(swagger.json, swagger.yaml and doc.go) (default: "./docs")
+   --parseVendor                          Parse go files in 'vendor' folder, disabled by default (default: false)
+   --parseDependency                      Parse go files in outside dependency folder, disabled by default (default: false)
+   --markdownFiles value, --md value      Parse folder containing markdown files to use as description, disabled by default
+   --codeExampleFiles value, --cef value  Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
+   --parseInternal                        Parse go files in internal packages, disabled by default (default: false)
+   --generatedTime                        Generate timestamp at the top of docs.go, true by default (default: false)
+   --parseDepth                        	  Dependency parse depth (default: 100)
+   --help, -h                             show help (default: false)
 ```
 
 ## Supported Web Frameworks
@@ -92,6 +96,7 @@ OPTIONS:
 - [net/http](https://github.com/swaggo/http-swagger)
 - [flamingo](https://github.com/i-love-flamingo/swagger)
 - [fiber](https://github.com/arsmn/fiber-swagger)
+- [atreugo](https://github.com/Nerzal/atreugo-swagger)
 
 ## How to use it with Gin
 
@@ -375,6 +380,7 @@ When a short string in your documentation is insufficient, or you need images, c
 | header      | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment`                            |
 | router      | Path definition that separated by spaces. `path`,`[httpMethod]`                                                            |
 | x-name      | The extension key, must be start by x- and take only json value.                                                           |
+| x-codeSample      | Optional Markdown usage. take `file` as parameter. This will then search for a file named like the summary in the given folder.                                      |
 | deprecated  | Mark endpoint as deprecated.                                                                                               |
 
 

cmd/swag/main.go

@@ -19,6 +19,7 @@ const (
 	parseVendorFlag      = "parseVendor"
 	parseDependencyFlag  = "parseDependency"
 	markdownFilesFlag    = "markdownFiles"
+	codeExampleFilesFlag = "codeExampleFiles"
 	parseInternalFlag    = "parseInternal"
 	generatedTimeFlag    = "generatedTime"
 	parseDepthFlag       = "parseDepth"
@@ -67,6 +68,12 @@ var initFlags = []cli.Flag{
 		Value:   "",
 		Usage:   "Parse folder containing markdown files to use as description, disabled by default",
 	},
+	&cli.StringFlag{
+		Name:    codeExampleFilesFlag,
+		Aliases: []string{"cef"},
+		Value:   "",
+		Usage:   "Parse folder containing code example files to use for the x-codeSamples extension, disabled by default",
+	},
 	&cli.BoolFlag{
 		Name:  parseInternalFlag,
 		Usage: "Parse go files in internal packages, disabled by default",
@@ -92,17 +99,18 @@ func initAction(c *cli.Context) error {
 	}
 
 	return gen.New().Build(&gen.Config{
-		SearchDir:          c.String(searchDirFlag),
-		Excludes:           c.String(excludeFlag),
-		MainAPIFile:        c.String(generalInfoFlag),
-		PropNamingStrategy: strategy,
-		OutputDir:          c.String(outputFlag),
-		ParseVendor:        c.Bool(parseVendorFlag),
-		ParseDependency:    c.Bool(parseDependencyFlag),
-		MarkdownFilesDir:   c.String(markdownFilesFlag),
-		ParseInternal:      c.Bool(parseInternalFlag),
-		GeneratedTime:      c.Bool(generatedTimeFlag),
-		ParseDepth:         c.Int(parseDepthFlag),
+		SearchDir:           c.String(searchDirFlag),
+		Excludes:            c.String(excludeFlag),
+		MainAPIFile:         c.String(generalInfoFlag),
+		PropNamingStrategy:  strategy,
+		OutputDir:           c.String(outputFlag),
+		ParseVendor:         c.Bool(parseVendorFlag),
+		ParseDependency:     c.Bool(parseDependencyFlag),
+		MarkdownFilesDir:    c.String(markdownFilesFlag),
+		ParseInternal:       c.Bool(parseInternalFlag),
+		GeneratedTime:       c.Bool(generatedTimeFlag),
+		CodeExampleFilesDir: c.String(codeExampleFilesFlag),
+		ParseDepth:          c.Int(parseDepthFlag),
 	})
 }
 

example/celler/controller/examples.go

@@ -22,7 +22,6 @@ import (
 // @Router /examples/ping [get]
 func (c *Controller) PingExample(ctx *gin.Context) {
 	ctx.String(http.StatusOK, "pong")
-	return
 }
 
 // CalcExample godoc

example/markdown/api/api.go

@@ -7,16 +7,16 @@ import (
 
 // User example
 type User struct {
-	Id       int64
+	ID       int64
 	Email    string
 	Password string
 }
 
 // UsersCollection example
 type UsersCollection []User
 
-// APIError example
-type APIError struct {
+// Error example
+type Error struct {
 	ErrorCode    int
 	ErrorMessage string
 	CreatedAt    time.Time

gen/gen.go

@@ -66,6 +66,9 @@ type Config struct {
 	// GeneratedTime whether swag should generate the timestamp at the top of docs.go
 	GeneratedTime bool
 
+	// CodeExampleFilesDir used to find code example files, which can be used for x-codeSamples
+	CodeExampleFilesDir string
+
 	// ParseDepth dependency parse depth
 	ParseDepth int
 }
@@ -78,7 +81,8 @@ func (g *Gen) Build(config *Config) error {
 
 	log.Println("Generate swagger docs....")
 	p := swag.New(swag.SetMarkdownFileDirectory(config.MarkdownFilesDir),
-		swag.SetExcludedDirsAndFiles(config.Excludes))
+		swag.SetExcludedDirsAndFiles(config.Excludes),
+		swag.SetCodeExamplesDirectory(config.CodeExampleFilesDir))
 	p.PropNamingStrategy = config.PropNamingStrategy
 	p.ParseVendor = config.ParseVendor
 	p.ParseDependency = config.ParseDependency

go.mod

@@ -4,16 +4,14 @@ require (
 	github.com/KyleBanks/depth v1.2.1
 	github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751
 	github.com/ghodss/yaml v1.0.0
-	github.com/gin-gonic/gin v1.4.0
-	github.com/go-openapi/jsonreference v0.19.3 // indirect
-	github.com/go-openapi/spec v0.19.4
+	github.com/gin-gonic/gin v1.6.3
+	github.com/go-openapi/spec v0.19.9
 	github.com/gofrs/uuid v3.3.0+incompatible
-	github.com/shopspring/decimal v1.2.0
-	github.com/stretchr/testify v1.4.0
+	github.com/stretchr/testify v1.6.1
 	github.com/swaggo/files v0.0.0-20190704085106-630677cd5c14
 	github.com/swaggo/gin-swagger v1.2.0
-	github.com/urfave/cli/v2 v2.1.1
-	golang.org/x/tools v0.0.0-20190614205625-5aca471b1d59
+	github.com/urfave/cli/v2 v2.2.0
+	golang.org/x/tools v0.0.0-20200820010801-b793a1359eac
 )
 
 go 1.13