gin-swagger生成API文档
github地址：https://github.com/swaggo/gin-swagger
下载安装cmd/swag命令工具包
先下载cmd包，才能执行相关命令
go get -u github.com/swaggo/swag/cmd/swag
我开始没成功，后来进入$GOPATH/bin/ 目录执行go get github.com/swaggo/swag/cmd/swag ，在bin目录下生成一个swag.exe文件，把$GOPATH/bin/ 添加到Path环境变量才算成功
执行初始化命令
swag init // 注意，一定要和main.go处于同一级目录
初始化命令，在根目录生成一个docs文件夹
- docs/docs.go
示例程序
package main import ( "apiwendang/controller" _ "apiwendang/docs" "github.com/gin-gonic/gin" swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" ) // @title Docker监控服务 // @version 1.0 // @description docker监控服务后端API接口文档 // @contact.name API Support // @contact.url http://www.swagger.io/support // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host 127.0.0.1:9009 // @BasePath func main() { r := gin.New() r.Use(Cors()) //url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition r.POST("/test/:id", controller.Test) r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) r.Run(":9009") } func Cors() gin.HandlerFunc { return func(c *gin.Context) { c.Header("Access-Control-Allow-Origin", "*") c.Next() } }
再次执行初始化命令
swag init // 注意，一定要和main.go处于同一级目录
初始化命令，在根目录生成一个docs文件夹，内含三个文件
- docs/docs.go
- swagger.json
- swagger.yaml
访问swagger文档：http://localhost:9009/swagger/index.html
====
API操作
// @Summary 接口概要说明 // @Description 接口详细描述信息 // @Tags 用户信息 //swagger API分类标签, 同一个tag为一组 // @accept json //浏览器可处理数据类型，浏览器默认发 Accept: */* // @Produce json //设置返回数据的类型和编码 // @Param id path int true "ID" //url参数：（name；参数类型[query(?id=),path(/123)]；数据类型；required；参数描述） // @Param name query string false "name" // @Success 200 {object} Res {"code":200,"data":null,"msg":""} //成功返回的数据结构， 最后是示例 // @Failure 400 {object} Res {"code":200,"data":null,"msg":""} // @Router /test/{id} [get] //路由信息，一定要写上
如果参数是body
// @Param user body models.User true "user"
1. 返回字符串
// @Summary 测试接口 // @Description 描述信息 // @Success 200 {string} string "ok" // @Router / [get] func Test(ctx *gin.Context) { ctx.JSON(200, "ok") }
2. 返回gin.H
// @Summary 测试接口 // @Description 描述信息 // @Success 200 {object} gin.H // @Router / [get] func Test(ctx *gin.Context) { ctx.JSON(200, gin.H{ "code":200, }) }
如果直接返回gin.H这种json结构，要用@Success 200 {object} gin.H，但是这种编译很慢，最好还是返回一种固定的结构体
3. 返回固定struct结构体
type Res struct { Code int `json:"code"` Data interface{} `json:"data"` Msg string `json:"msg"` } func returnMsg(ctx *gin.Context, code int, data interface{}, msg string) { ctx.JSON(200, Res{ Code:code, Data:data, Msg:msg, }) } // @Summary 测试接口 // @Description 描述信息 // @Success 200 {object} Res {"code":200,"data":null,"msg":""} // @Router / [get] func Test(ctx *gin.Context) { ctx.JSON(200, Res{ Code:200, Data:nil, Msg:"", }) }
POST请求：
models/user.go type User struct { ID int `json:"id"` Name string `json:"name"` } ================== type Res struct { Code int `json:"code"` Data interface{} `json:"data"` Msg string `json:"msg"` } func returnMsg(ctx *gin.Context, code int, data interface{}, msg string) { ctx.JSON(200, Res{ Code:code, Data:data, Msg:msg, }) } func Test1(ctx *gin.Context) { returnMsg(ctx, 500, "aaa", "bbb") } // @Summary 接口概要说明 // @Description 接口详细描述信息 // @Tags 测试 // @Security Bearer // @Produce json // @Param id path int true "ID" // @Param user body models.User true "user" // @Success 200 {object} Res {"code":200,"data":null,"msg":""} // @Router /test/{id} [post] func Test(ctx *gin.Context) { fmt.Println(ctx.Param("id")) var input models.User if err := ctx.ShouldBindJSON(&input); err!=nil{ returnMsg(ctx, 402, nil, err.Error()) return } fmt.Println(input) returnMsg(ctx, 200, "aaa", "bbb") }
如果出现错误：Undocumented TypeError: Failed to fetch
查看具体错误信息，浏览器F12，发现是跨域问题：
Failed to load http://127.0.0.1:9009/test/2: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:9009' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
设置允许跨域就OK了
简单版本：
func Cors() gin.HandlerFunc { return func(c *gin.Context) { c.Header("Access-Control-Allow-Origin", "*") c.Next() } }
复杂的可以根据实际需求添加：
func Cors() gin.HandlerFunc { return func(c *gin.Context) { method := c.Request.Method origin := c.Request.Header.Get("Origin") var headerKeys []string for k, _ := range c.Request.Header { headerKeys = append(headerKeys, k) } headerStr := strings.Join(headerKeys, ", ") if headerStr != "" { headerStr = fmt.Sprintf("access-control-allow-origin, access-control-allow-headers, %s", headerStr) } else { headerStr = "access-control-allow-origin, access-control-allow-headers" } if origin != "" { c.Writer.Header().Set("Access-Control-Allow-Origin", "*") c.Header("Access-Control-Allow-Origin", "*") // 这是允许访问所有域 c.Header("Access-Control-Allow-Methods", "POST, GET, OPTIONS, PUT, DELETE,UPDATE") //服务器支持的所有跨域请求的方法,为了避免浏览次请求的多次'预检'请求 // header的类型 c.Header("Access-Control-Allow-Headers", "Authorization, Content-Length, X-CSRF-Token, Token,session,X_Requested_With,Accept, Origin, Host, Connection, Accept-Encoding, Accept-Language,DNT, X-CustomHeader, Keep-Alive, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Pragma") // 允许跨域设置 可以返回其他子段 c.Header("Access-Control-Expose-Headers", "Content-Length, Access-Control-Allow-Origin, Access-Control-Allow-Headers,Cache-Control,Content-Language,Content-Type,Expires,Last-Modified,Pragma,FooBar") // 跨域关键设置 让浏览器可以解析 c.Header("Access-Control-Max-Age", "172800") // 缓存请求信息 单位为秒 c.Header("Access-Control-Allow-Credentials", "false") // 跨域请求是否需要带cookie信息 默认设置为true c.Set("content-type", "application/json") // 设置返回格式是json } //放行所有OPTIONS方法 //if method == "OPTIONS" { // c.JSON(http.StatusOK, "Options Request!") //} if method == "OPTIONS" { c.AbortWithStatus(204) return } // 处理请求 c.Next() // 处理请求 } }
