1. swagger.go文件

使用_导入所有包含文档注解的包

package main
import (
    _ "github.com/teambition/swaggo/example/pkg/api"
)
// @Version 1.0.0
// @Title Swagger Example API
// @Description Swagger Example API
// @Schemes http,wss
// @Host 127.0.0.1:3000
// @BasePath /api
// @Name teambition
// @Contact [email protected]
// @URL http://teambition.com
// @TermsOfServiceUrl http://teambition.com/
// @License Apache
// @LicenseUrl http://teambition.com/
// @Consumes json,xml
// @Produces json,xml


@Version API版本号

@Title 服务名称

@Description 服务描述

@Schemes 服务协议(http，websockes)

@Host 可用服务器地址，用于测试

@BasePath API路径的前缀

@Name 作者名字

@Contact 作者联系方式

@URL 作者个人页

@TermsOfServiceUrl 服务条款说明地址

@License 开源协议

@LicenseUrl 协议地址

@Consumes 方法接收参数的类型,多选用,隔开,包括(json,xml,plain,form,formData,stream)

@Produces 方法返回参数的类型,包括(json,xml,plain,html,form,formData,stream)

2. Controller注解

// @Private reason
// @Name Controller
// @Description test apis
type Controller struct {
}


@Private 存在表示不公开该Controller下的所有API文档

  • reason 私有说明,可选值

@Name 资源名称

@Description 资源描述

3. Handler注解

// @Private reason
// @Title Hello
// @Summary say hello
// @Description this is a method to say hello
// @Deprecated true
// @Consumes json
// @Produces json
// @Param some_id path int true "Some ID"
// @Param offset query int true "Offset"
// @Param limit query int true "Limit"
// @Success 200 StructureWithEmbededPointer "Success!"
// @Failure 400 APIError "We need ID!!"
// @Failure 404 APIError "Can not find ID"
// @Router GET /say/hello/{some_id}
func (c *Controller) Hello(rw http.ResponseWriter, req *http.Request) {
}


@Private 存在,表示不公开该API文档

@Title 方法名

@Summary 方法简介

@Description 方法的详细描述

@Deprecated 该接口不再使用

@Consumes 方法接收参数的类型,多选用,隔开,包括(json,xml,plain,form,formData,stream)

@Produces 方法返回参数的类型,包括(json,xml,plain,html,form,formData,stream)

@Param 参数列表,用空格隔开

// @Param some_id path int true "Some ID" 6


  • some_id 参数名称

  • path 参数类型,包括(path:路径参数,query:请求参数,header:请求头,form:表单,body:请求体)

  • int 数据类型,支持Golang原生类型(int,string,bool...),支持自定义类型(your_package.YourType)

  • true 参数是否必须,可选值,使用-占位

  • "Some ID" 参数的简要描述,可选值,使用-占位

  • 6 默认值,可选值

@Success 成功返回示例,用空格隔开

// @Success 200 StructureWithEmbededPointer "Success!"


  • 200 http返回码

  • StructureWithEmbededPointer 返回数据类型,支持Golang原生类型([]int,int,string,bool...),支持自定义类型(your_package.YourType)

  • "Success!" 结果描述,必须

@Failure 失败返回示例,用空格隔开

@Router 路由定义,用空格隔开

// @Router GET /say/hello/{some_id}


  • GET 请求方法,支持(GET,POST,PUT,PATCH,DELETE,HEAD,OPTIONS)

  • /say/hello/{some_id} 路由路径, {some_id}在**@Param**中定义

4. Go结构体标签

type SimpleStructure struct {
    Id float32 `json:"id" swaggo:"true,my id,19"`
    Name string `json:"name" swaggo:"true,,xus"`
    Age int `json:"age" swaggo:"true,the user age,18"`
    CTime time.Time `json:"ctime" swaggo:"true,create time"`
    Sub subpackage.SimpleStructure `json:"sub" swaggo:"true"`
    I TypeInterface `json:"i" swaggo:"true"`
}


swaggo:"true,dfsdfdsf,19" swagger文档相关标签，用,隔开

  • true 是否必须,可选值,缺省用,隔开

  • my id 文档描述,可选值,缺省用,隔开

  • 19 默认值,可选值,缺省用,隔开



转载地址:

 https://github.com/teambition/swaggo/wiki/Declarative-Comments-Format#1-swaggergo文件