swagger 工具和 golang 如何深度联动？本文介绍了 swaggos 文档生成器。

golang 生成 swagger 文档一直没有很好的方式，官方推荐的是通过注释生成文档，但是缺陷是注释很难写，IDE 又没有自动提示

今天发现一款不错的三方包，可以直接基于 golang 代码生成文档

github.com/clearcodecn/swaggos

Swaggos

swaggos 是一个 golang 版本的 swagger 文档生成器，提供了 native code 包装器。

安装

 go get -u github.com/clearcodecn/swaggos

使用

创建实例

hostapiPrefix
  doc := swaggos.Default()

    doc.HostInfo("www.github.com","/api/v1")

    // default is application/json

    doc.Produces("application/json")

    // default is application/json

    doc.Consumes("application/json")

Authorization

oauth2basic authapiKey

Oauth2

  var scopes = []string{"openid"}

    var tokenURL = "https://yourtokenurl"

    var authURL = "https://yourAuthURL"

    // config password flow

    doc.Oauth2Password(tokenURL,scopes)

    // access code

    doc.Oauth2AccessCode(authURL,tokenURL,scopes)

    // client

    doc.Oauth2Client(tokenURL,scopes)

    // implicit

    doc.Oauth2Implicit(authURL,scopes)

Basic Auth

 doc.Basic()

自定义 Token

access_token
 doc.JWT("access_token")

公共参数

 // will create header param in each request

    doc.Header("name","description",true)

    doc.Query("name","description",true)

    doc.Form("name","description",true)

请求路劲

path 是一个请求的实例，支持流式写法。
   // 创建一个 path

    path := doc.Get("user_information")

    path.

        Tag("tagName"). // 创建 tag

        Summary("summary"). // 总结

        Description("...."). // 描述

        ContentType("application/json","text/html"). // 请求/响应类型

    // path params

    path.Form("key",swaggos.Attribute{})

    // form files

    path.FormFile("file",swaggos.Attribute{Required:true})

    // form object reference

    path.FormObject(new(User))

    // query object

    path.QueryObject(new(User))

    // body

    path.Body(new(User))

    // json response

    path.JSON(new(User))

    // Attribute rules:

    type Attribute struct {

    Model      string      `json:"model"`          // key name

    Description string      `json:"description"`    // description

    Required    bool        `json:"required"`      // if it's required

    Type        string      `json:"type"`          // the param type

    Example    interface{} `json:"example"`        // example value

    Nullable  bool          `json:"nullable,omitempty"`    // if it's nullable

    Format    string        `json:"format,omitempty"`      // format

    Title    string        `json:"title,omitempty"`        // title

    Default  interface{}  `json:"default,omitempty"`      // default value

    Maximum  *float64      `json:"maximum,omitempty"`      // max num

    Minimum  *float64      `json:"minimum,omitempty"`      // min num

    MaxLength *int64        `json:"maxLength,omitempty"`    // max length

    MinLength *int64        `json:"minLength,omitempty"`    // min length

    Pattern  string        `json:"pattern,omitempty"`      // regexp pattern

    MaxItems  *int64        `json:"maxItems,omitempty"`    // max array length

    MinItems  *int64        `json:"minItems,omitempty"`    // min array length

    Enum      []interface{} `json:"enum,omitempty"`        // enum values

    Ignore    bool          `json:"ignore"`                // if it's ignore

    Json      string        `json:"json"`                  // key name

    }

路劲响应

   // 响应 json，创建 model

    path.JSON(new(Response))

    // will provide a example response

    // 400

    path.BadRequest(map[string]interface{

            "data": nil,

            "code": 400,

    })

    // 401

    path.UnAuthorization(v)

    // 403

    path.Forbidden(v)

    // 500

    path.ServerError(v)

分组

分组将对 api 进行分组，组下面的所有路劲会共享分组的公共参数
  g := doc.Group("/api/v2")

    g.Get("/user") // --> /api/v2/user

        // ... other methods

        g.Form ...

        g.Query ...

        g.Header ...

全局响应

   doc.Response(200, new(Success))

    doc.Response(400, new(Fail))

    doc.Response(500, new(ServerError))

结构体的 tag 支持

 type User struct {

        // 字段名称  model > json

        // this example field name will be m1

        ModelName string `model:"m1" json:"m2"`

        // 字段名会是  username

        Username string `json:"username"`

        //  字段名会是 Password

        Password string

        // 会被忽略

        Ignored `json:"-"`

        // 是否必须

        Required string `required:"true"`

        // 字段的描述

        Description string `description:"this is description"`

        // 字段的类型：string,integer,time,number,boolean,array...

        Type string `type:"time"`

        // 默认值 abc

        DefaultValue string `default:"abc"`

        // 最大值 100

        Max float64 `maximum:"100"`

        // 最小值 0

        Min float64 `min:"0"`

        // 最大长度 20

        MaxLength string `maxLength:"20"`

        // 最小长度 10

        MinLength string `minLength:"10"`

        // 正则表达式规则

        Pattern string `pattern:"\d{0,9}"`

        // 数组长度 小于 3

        MaxItems []int `maxItems:"3"`

        // 数组长度大于 3

        MinItem []int `minItems:"3"`

        // 枚举，用 , 分割

        EnumValue int `enum:"a,b,c,d"`

        // 忽略字段

        IgnoreField string `ignore:"true"`

        // 匿名字段规则：

        // 如果是一个基本类型，则直接添加，

        // 如果是一个 数组，也将直接添加

        // 如果是一个结构体 但是带了 json tag，将会作为一个字段

        // 如果是一个结构体 带没有 json tag，将会将里面的子字段添加上该结构体上

        Anonymous

    }

构建 json 和 yaml

    data,_ := doc.Build()

    fmt.Println(string(data))

    => this is the swagger schema in json format

    data,_ := doc.Yaml()

    fmt.Println(string(data))

    => yaml format

提供 http 服务

http.Handle("/swagger",doc)