swaggos v0.0.2 发布,golang native code swagger 文档生成器

栏目: 软件资讯 · 发布时间: 4年前

内容简介:v0.0.2 删除 gin wrapper, 将不针对任何框架做wrapper 优化对auth的支持,basic/oauth2/apiKey doc上增加Form/Query/Header便利函数 新增一些示例 如 开源中国的 openapi: examples/osc/main.go 增加对 http han...

v0.0.2

  • 删除 gin wrapper, 将不针对任何框架做wrapper
  • 优化对auth的支持,basic/oauth2/apiKey
  • doc上增加Form/Query/Header便利函数
  • 新增一些示例 如 开源中国的 openapi: examples/osc/main.go
  • 增加对 http handler 的支持

Swaggos

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

安装

    go get -u github.com/clearcodecn/swaggos

使用

创建实例

创建一个新的实例,配置一些基本信息 host 和 apiPrefix

    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

项目支持swagger的所有鉴权方式: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

会在header中增加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)

Tips: examples 目录下面有少量的示例

github: https://github.com/clearcodecn/swaggos

gitee: https://gitee.com/wocaa/swaggos


以上就是本文的全部内容,希望本文的内容对大家的学习或者工作能带来一定的帮助,也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

数据结构基础

数据结构基础

[美]Ellis Horowitz 霍罗维兹 / 朱仲涛 / 清华大学出版社 / 2009-3 / 49.00元

《数据结构基础(C语言版)(第2版)》是最经典数据结构教材的最新版本,国内外大多数的同类教材都是以《数据结构基础(C语言版)(第2版)》为蓝本编写而来的。《数据结构基础(C语言版)(第2版)》用C作为描述语言,全面而生动地介绍了数据结构的有关知识,如数组、栈、队列、链表、树和图,以及构成所有软件基础的排序散列技术。此外,《数据结构基础(C语言版)(第2版)》还介绍了各种高级或特殊数据结构,如优先级......一起来看看 《数据结构基础》 这本书的介绍吧!

图片转BASE64编码
图片转BASE64编码

在线图片转Base64编码工具

html转js在线工具
html转js在线工具

html转js在线工具

RGB CMYK 转换工具
RGB CMYK 转换工具

RGB CMYK 互转工具