关于golang:go使用swagger生成接口文档

1. 装置 swag 工具
   go get -u github.com/swaggo/swag/cmd/swag

2. 在入口文件写上我的项目的简介

   package main
   
   import (
   "flag"
   "open-api/internal/app/fund"
   )
   
   // @title 这里写题目 `
   // @version 1.0`
   // @description 这里写形容信息 `
   // @termsOfService [http://swagger.io/terms/](http://swagger.io/terms/)`
   // @contact.name 这里写联系人信息 `
   // @contact.url [http://www.swagger.io/support](http://www.swagger.io/support)`
   // @contact.email support@swagger.io`
   // @license.name Apache 2.0`
   // @license.url [http://www.apache.org/licenses/LICENSE-2.0.html](http://www.apache.org/licenses/LICENSE-2.0.html)`
   // @host 这里写接口服务的 host`
   // @BasePath 这里写 base path`
   
   func main() {
   var configPath string
   flag.StringVar(&configPath, "config", "./configs", "config path")
   flag.Parse()
   fund.Run(configPath)
   }

3. 在你代码中解决申请的接口函数（通常位于 controller 层）按如下形式写上正文：

   // @Summary 领取列表
   // @Description 获取领取列表
   // @Accept  json
   // @Produce  json
   // @param Authorization header string true "验证参数 Bearer 和 token 空格拼接"
   // @Param  body body st.PaySearch true "交款查问参数"
   // @Success 200 {object} response.Response{data=st.PayListResponse}
   // @Failure 500 {object} response.Response
   // @Router /app/pay/list [post]
   func PayList(ctx *gin.Context) {
   var (
       paySearch st.PaySearch
       data      []st.PayListResponse
       err       error
   )
   if err := ctx.Bind(&paySearch); err != nil {response.Failed(ctx, response.InvalidParams, response.GetMsg(response.InvalidParams), data, err)
       return
   }
   data, err = logic.GetPayListNew(p)
   
   if err != nil {response.Failed(ctx, response.Error, response.GetMsg(response.Error), data, err)
       return
   }
   response.Successed(ctx, response.Success, response.GetMsg(response.Success), data)
   }

4. 下面正文中参数类型应用了 object，st.PaySearch st.PayListResponse response.Response 具体定义如下：

   type Response struct {
   Code int         `json:"code"`
   Msg  string      `json:"msg"`
   Data interface{} `json:"data"`}
   
   type PayListResponse struct {
   HouseBase
   Id                 int             `json:"id"`
   Name               string          `json:"name"`
   PayAmount          decimal.Decimal `json:"pay_amount"`
   PayArea            decimal.Decimal `json:"pay_area"`
   BankAccountingTime TimeShowDay     `json:"bank_accounting_time"`
   BankName           string          `json:"bank_name"`
   AccountCode        string          `json:"account_code"`
   BankCode           string          `json:"bank_code"`
   }
   
   type PaySearch struct {
   Phone  string `form:"phone" binding:"required,phoneValid"`
   Status string `form:"status" binding:"required,oneof='0''1'"`
   }

5. 生成文档

   swag init -g cmd/main.go  // -g 指定 main.go 的地位，我这边是在 cmd 文件中
   此时目录中多了 docs
   ./docs
   ├── docs.go
   ├── swagger.json
   └── swagger.yaml

6. 引入 gin-swagger 渲染文档数据, 利用条件编译来决定是否编译 swagger，因为线上运行时，不须要 swagger

doc_swag.go

// +build doc

package router

import (
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

func init() {swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)
}

swag.go 目前是空的

router.go

package router

import (
    _ "open-api/docs"
    "open-api/internal/app/fund/controller"
    "open-api/internal/app/fund/middleware"
    validator2 "open-api/pkg/validator"

    "github.com/gin-gonic/gin/binding"
    "github.com/go-playground/validator/v10"

    "github.com/gin-gonic/gin"
)

var swagHandler gin.HandlerFunc

func InitRouter() *gin.Engine {r := gin.New()
    r.Use(gin.Logger())
    r.Use(gin.Recovery())
    r.Use(middleware.Cors())

    // 开启 swag
    if swagHandler != nil {r.GET("/swagger/*any", swagHandler)
    }

    if v, ok := binding.Validator.Engine().(*validator.Validate); ok {_ = v.RegisterValidation("phoneValid", validator2.PhoneValidHook)
    }
    return r
}

7. 在 goland 中配置 build 参数，以便本地调试

至此就实现了。如有问题请私信我。