Declarative Comments Format

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 swagger@teambition.com
// @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 默认值,可选值,缺省用,隔开