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

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

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

package mainimport ("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 stringflag.StringVar(&configPath, "config", "./configs", "config path")flag.Parse()fund.Run(configPath)}

在你代码中解决申请的接口函数（通常位于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)}

下面正文中参数类型应用了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 {HouseBaseId                 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'"`}

生成文档

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

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

doc_swag.go

// +build docpackage routerimport (    swaggerFiles "github.com/swaggo/files"    ginSwagger "github.com/swaggo/gin-swagger")func init() {    swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)}

swag.go 目前是空的

router.go

package routerimport (    _ "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.HandlerFuncfunc 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}

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

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