swagger注解说明

【swagger注解说明】前言:使用swagger的主要好处就是不用手动写文档了,通过注解就可以自动化文档。 文档和代码同步更新,代码更新之后不需要再更新文档。使用Swagger框架可以调试API,在浏览器端可以看到更多的`request`和`response`信息。本文章重点描述下swagger应用注释说明。
1.swagger应用注释 示例:
package controllers

import "github.com/astaxie/beego"

// CMS API
type CMSController struct {
beego.Controller
}

func (c *CMSController) URLMapping() {
c.Mapping("StaticBlock", c.StaticBlock)
c.Mapping("Product", c.Product)
}

// @Title getStaticBlock
// @Description get all the staticblock by key
// @Paramkeypathstringtrue"The email for login"
// @Success 200 {object} models.ZDTCustomer.Customer
// @Failure 400 Invalid email supplied
// @Failure 404 User not found
// @router /staticblock/:key [get]
func (c *CMSController) StaticBlock() {

}

// @Title Get Product list
// @Description Get Product list by some info
// @Success 200 {object} models.ZDTProduct.ProductList
// @Paramcategory_idqueryint false"category id"
// @Parambrand_idqueryint false"brand id"
// @Paramqueryquerystringfalse"query of search"
// @Paramsegment querystringfalse"segment"
// @Paramsortquerystringfalse"sort option"
// @Paramdirquerystringfalse"direction asc or desc"
// @Paramoffsetqueryintfalse"offset"
// @Paramlimitqueryintfalse"count limit"
// @Parampricequeryfloatfalse"price"
// @Paramspecial_pricequeryboolfalse"whether this is special price"
// @Paramsizequerystringfalse"size filter"
// @Paramcolorquerystringfalse"color filter"
// @Paramformatqueryboolfalse"choose return format"
// @Failure 400 no enough input
// @Failure 500 get products common error
// @router /products [get]
func (c *CMSController) Product() {

}
首先是 CMSController 定义上面的注释,这个是用来显示这个模块的作用。接下来就是每一个函数上面的注释,这里列出来支持的各种注释:

  • @Title
这个 API 所表达的含义,是一个文本,空格之后的内容全部解析为 title
  • @Description
    这个 API 详细的描述,是一个文本,空格之后的内容全部解析为 Description

  • @Param
    参数,表示需要传递到服务器端的参数,有五列参数,使用空格或者 tab 分割,五个分别表示的含义如下
    1.参数名
    2.参数类型,可以有的值是 formData、query、path、body、header,formData 表示是 post 请求的数据,query 表示带在 url 之后的参数,path 表示请求路径上得参数,例如上面例子里面的 key,body 表示是一个 raw 数据请求,header 表示带在 header 信息中得参数。
    3.参数类型
    4.是否必须
    5.注释

  • @Success
    成功返回给客户端的信息,三个参数,第一个是 status code。第二个参数是返回的类型,必须使用 {} 包含,第三个是返回的对象或者字符串信息,如果是 {object} 类型,那么 bee 工具在生成 docs 的时候会扫描对应的对象,这里填写的是想对你项目的目录名和对象,例如 models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的 ProductList 对象。
    三个参数必须通过空格分隔

  • Failure
    失败返回的信息,包含两个参数,使用空格分隔,第一个表示 status code,第二个表示错误信息

  • @router
    路由信息,包含两个参数,使用空格分隔,第一个是请求的路由地址,支持正则和自定义路由,和之前的路由规则一样,第二个参数是支持的请求方法,放在 [] 之中,如果有多个方法,那么使用 , 分隔。

    推荐阅读