Go|Gin 快速使用Swagger

安装

go get -u github.com/swaggo/swag/cmd/swag

检查 自己的 GOPATH 是否再环境变量中。可通过 ​​go env​​ 查看

运行

swag init

会再目录下生成docs 文件夹

│  go.mod
│  go.sum
│  main.exe
│  main.go
│
├─docs
│      docs.go
│      swagger.json
│      swagger.yaml

例子

package main

import (
  "github.com/gin-gonic/gin"
  ginSwagger "github.com/swaggo/gin-swagger"
  swaggerFiles "github.com/swaggo/files"
  _ "hello/docs" // 这里需要引入本地已生成文档
  "net/http"
)

// @title        廖圣平博客
// @version      1.0
// @description  swagger 入门使用例子
func main() {
  r := gin.Default()
  r.GET("/ping", func(c *gin.Context) {
    c.JSON(200, gin.H{
      "message": "pong",
    })
  })
  r.GET("/get", Get)
  r.POST("/post", Post)
  r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
  //r.GET("/swagger/*any", handleReDoc)
  r.Run() // listen and serve on 0.0.0.0:8080
}

type Response struct{
  Code uint32 `json:"code"`
  Message uint32 `json:"message" description:"描述"`
  Data interface{} `json:"data"`
}

type Requests struct{
  Code uint32 `json:"code"`
  Message uint32 `json:"message"`
  Data interface{} `json:"data"`
}

type ResponseError struct{
  Code uint32 `json:"code"`
  Message uint32 `json:"message"`
}

// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  [e-mail]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @securityDefinitions.basic  BasicAuth



// @Summary  GET请求的例子
// @Schemes
// @Description  GET请求的例子描述
// @Tags         请求例子
// @Param        id  query  int  true  "Account ID"
// @Accept       json
// @Produce      json
// @Success      200  {object}  Response
// @Router       /get [get]
func Get(c *gin.Context){
  res := Response{ Code: 1001, Message: 1, Data: "connect success !!!"}
  c.JSON(http.StatusOK, res)
}


// @Summary      POST请求的例子
// @Description  POST请求的例子描述
// @Tags         请求例子
// @Param        body  body  Requests  true  "JSON数据"
// @Accept       json
// @Produce      json
// @Success      200  {object}  Response       -->  成功后返回数据结构
// @Failure      400  {object}  ResponseError  -->  失败后返回数据结构
// @Router       /post [post]
func Post(c *gin.Context){
  res := Response{ Code: 1001, Message: 1, Data: "connect success !!!"}
  c.JSON(http.StatusOK, res)
}

go run main.go

生成一个GET 请求。

格式化备注信息

swag fmt

参数

添加头信息

// @param Authorization header string true "验证参数Bearer和token空格拼接"

文件上传例子

// @Param   file formData file true  "this is a test file"

请求方式

// @Accept  multipart/form-data

忽略字段

type Ignored struct {
  Field5 string `swaggerignore:"true"`
}

对模型进行重命名

type Resp struct {
    Code int
}//@name Response

枚举使用

// @Param        enumstring  query     string  false  "string enums"    Enums(A, B, C)
// @Param        enumint     query     int     false  "int enums"       Enums(1, 2, 3)
// @Param        enumnumber  query     number  false  "int enums"       Enums(1.1, 1.2, 1.3)

字符串限制长度

// @Param        string      query     string  false  "string valid"    minlength(5)  maxlength(10)
// @Param        int         query     int     false  "int valid"       minimum(1)    maximum(10)

验证

// @Security     ApiKeyAuth
// @Security     OAuth2Implicit[admin, write]

swag 返回工具

// Auth godoc
// @Summary      Auth admin
// @Description  get admin info
// @Tags         accounts,admin
// @Accept       json
// @Produce      json
// @Success      200  {object}  model.Admin
// @Failure      400  {object}  httputil.HTTPError
// @Failure      401  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Security     ApiKeyAuth
// @Router       /admin/auth [post]
func (c *Controller) Auth(ctx *gin.Context) {
  authHeader := ctx.GetHeader("Authorization")
  if len(authHeader) == 0 {
    httputil.NewError(ctx, http.StatusBadRequest, errors.New("please set Header Authorization"))
    return
  }
  if authHeader != "admin" {
    httputil.NewError(ctx, http.StatusUnauthorized, fmt.Errorf("this user isn't authorized to operation key=%s expected=admin", authHeader))
    return
  }
  admin := model.Admin{
    ID:   1,
    Name: "admin",
  }
  ctx.JSON(http.StatusOK, admin)
}

• 数据例子

type Message struct {
  Message string `json:"message" example:"message"`
}

• 支持markdown

// @Description | 参数 | 说明 |备注|
// @Description | :-----: | :----: | :----: |
// @Description | 参数 | 说明 | 阿萨德 |