morlay/gin-swagger

[DEPRECATED]

Gin Swagger

Pick Swagger from code which wrote by gin

Rules

Path & Method

• pick path and method from *gin.Engine or *gin.RouterGroup
• path of *gin.RouterGroup will be prefix of path of *gin.Engine
• only support GET POST PUT PATCH HEAD DELETE OPTIONS
• gin-style router will be convert to swagger-style, :id => {id}, double check with parameter definitions, undefined path parameter will be use 0 instead.

Operation

• pick operation in scope of gin-handler (not support anonymous func, we need func name as operationId)
• name of gin-handler will be operationId
• only support single gin-handler.

Parameter

• struct type of variable req or request in scope of gin-handler will be used for picking parameters.
• tag in of struct field must be defined, expect body parameter, but need to use fieldName Body.
• tag json will be used as name
• struct type of anonymous struct field will be picked too.
• others will be same as Schema

Response

• status will be picked by gin-context render method.
• c.JSON will set schema by type of return value and with produce application/json
• c.HTML will with produce application/html
• c.Rediect c.Data and c.Render will be no responce

Schema

• only support json
• basic type will be translated, but json:"key,string" will force converting to string
• tag default will be set the default value, if it not exists, we will set field required
• tag validate will be set common validations, for example, validate:"@int[0,100)" will be { "minimum": 0, "exclusiveMinimum": true, "maximum": 100 }
• anonymous struct field will be used with allOf

Enums

• pick enum from commented swagger:enum type

• string enum from const

// swagger:enum State
type State int

const (
	STATE_UNKNOWN = iota
	STATE__ONE    // one
	STATE__TWO    // two
	STATE__THREE  // three
)

will be

{
  "enum": [
    "ONE",
    "TWO",
    "THREE"
  ],
  "x-enum-labels": [
    "one",
    "two",
    "three"
  ],
  "x-enum-type": "State"
}

• validate:"@string{ONE,TWO}" or validate:"@int{1,2}" will be used for partial pick enum values;

String format

• pick format from commented swagger:strfmt <format-name> type

Definitions

• only collect the named complex type, like struct type, slice type, map type

gin-swagger's Issues

scanner.addResponse should deal context.String

gin.context.String can be used to set response in gin handler; so this context.String should be considered in scanner.addResponse;

Wrong absolute gin path if relative gin path has no leading '/'

for example, I use gin.GET like this:

msapi := g.Group("msbackend/api")
msapi.GET("method/query", api.QueryMethod)

then in scanner.go 460, it will get a wrong absolute path: msbackend/apihttp_called_by_info_day/query

To excute gin-swagger meet that panic: interface conversion: ast.Expr is *ast.Ident, not *ast.BasicLit

panic: interface conversion: ast.Expr is *ast.Ident, not *ast.BasicLit

goroutine 1 [running]:
panic(0x497780, 0xc43138c580)
/usr/local/Cellar/go/1.7/libexec/src/runtime/panic.go:500 +0x1a1
github.com/morlay/gin-swagger/swagger.getRouterPathByCallExpr(0xc420559b80, 0xc42014f660, 0x0)
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/swagger/helpers.go:42 +0xd4
github.com/morlay/gin-swagger/swagger.(*Scanner).Scan(0xc434630500)
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/swagger/scanner.go:764 +0x42b
github.com/morlay/gin-swagger/swagger.(*Scanner).Output(0xc434630500, 0x519a37, 0xc)
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/swagger/scanner.go:779 +0x2b
github.com/morlay/gin-swagger/cmd.glob..func1(0x775600, 0x798e88, 0x0, 0x0)
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/cmd/cmd.go:28 +0x5c
github.com/morlay/gin-swagger/vendor/github.com/spf13/cobra.(*Command).execute(0x775600, 0xc42000c240, 0x0, 0x0, 0x775600, 0xc42000c240)
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/vendor/github.com/spf13/cobra/command.go:624 +0x44c
github.com/morlay/gin-swagger/vendor/github.com/spf13/cobra.(*Command).ExecuteC(0x775600, 0xc42006e058, 0x0, 0xc420143f10)
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/vendor/github.com/spf13/cobra/command.go:699 +0x367
github.com/morlay/gin-swagger/vendor/github.com/spf13/cobra.(*Command).Execute(0x775600, 0x0, 0x0)
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/vendor/github.com/spf13/cobra/command.go:658 +0x2b
github.com/morlay/gin-swagger/cmd.Execute()
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/cmd/cmd.go:33 +0x31
main.main()
/Users/square3/Project/go/src/github.com/morlay/gin-swagger/main.go:8 +0x14