swagger 完美API文檔的生成工具,免去繁瑣的面向wiki編程。java中可直接引用swagger依賴,spring全家桶對swagger也集成通過寫註解便可直接生成入參返回值的api接口文檔。go項目也有對應的swaggo集成。下面介紹如何在go工程中使用swaggo自動生成接口文檔。很簡單,三步走
一、項目download swaggo資源
//1.安裝swag client
go get -u github.com/swaggo/swag/cmd/swag
# 2.gin-swagger 中間件
$ go get github.com/swaggo/gin-swagger
# 3.swagger 內置文件
$ go get github.com/swaggo/gin-swagger/swaggerFiles
二、go web工程集成swaggo
1. gin router 處添加如下代碼(攔截器操作)
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
2.簡單舉例,更新接口api接口處添加註釋,注意按如下註解編寫註釋
// @Summary 編輯系統用戶
// @Description 編輯系統用戶 賬號、角色不予更新;只更新密碼和姓名
// @Tags 系統用戶模塊
// @Param userName formData string true "賬號"
// @Param password formData string false "密碼"
// @Param realName formData string true "用戶姓名"
// @Success 200 {string} json "{"msg": "添加成功"}"
// @Failure 401 {string} json "{"msg": "err.Error()"}"
// @Failure 402 {string} json "{"msg": "賬號已存在"}"
// @Failure 403 {string} json "{"msg": "添加失敗"}"
// @Router /user/update [post]
func (c UserController) Update(ctx *gin.Context) {
//代碼邏輯
}
注:註釋格式可參照:使用swaggo自動生成Restful API文檔
3. 同樣在router中添加 import _ "rig-mini/docs" ,然後terminal執行swag init 命令,啓動工程後訪問http://localhost:12343/swagger/index.html即可查看api詳情。
三、訪問swaggerUI頁面看結果
編寫好註釋的接口列表、uri、請求方式、接口parameter以及response ,一目瞭然,完美