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