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文件