swagger中的枚举、自定义类型和swaggerignore

swagger中的枚举、自定义类型和swaggerignore

想要一些低成本的接口文档，无疑swagger是最好的选择，对于Golang，我们选择的是swag，他可以将代码注释转换成swagger2.0文档。除了swag，还需要一个web框架的中间件包装器库。

详细介绍可以看官网，这里则介绍一些不起眼的东西，比如枚举该如何展示，自定义类型，忽略某些字段该如何去做

枚举

type ExampleRequest struct {
	UserId     int64    `json:"user_id,string" swaggertype:"string" example:"11111111111111"`        // 用户id
	Role       []string `json:"role" swaggertype:"array,integer" enums:"0,1,2" example:"0,1"`        // 角色id: 0-超级管理员 1-管理员，2-用户
	RoleString []string `json:"role_string" swaggertype:"array,integer" enums:"0,1,2" example:"0,1"` // 角色id: 0-超级管理员 1-管理员，2-用户
	Page       int      `json:"page" example:"1"`
	Limit      int      `json:"limit" example:"10"`
}

从例子中可以看出，我们只需要在结构体的tag中加上enums，我们只需要用逗号隔开即可。

自定义类型swaggertype

swaggertype允许我们去自定义类型，这里拿官方例子展示

type TimestampTime struct {
    time.Time
}
type Account struct {
    // Override primitive type by simply specifying it via `swaggertype` tag
    ID     sql.NullInt64 `json:"id" swaggertype:"integer"`
 
    // Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
    RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`
 
    // Array types can be overridden using "array,<prim_type>" format
    Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
}

swaggerignore

使用swaggerignore标签排除字段，这个常用在文件流上传使用

type UploadFileRequest struct {
	File        *multipart.FileHeader `json:"file" form:"file" binding:"required" swaggerignore:"true"` // 保存的文件
}

参考：https://promacanthus.netlify.app/tools/swagger/swagger-guide/#parameterType