- 安装swag 工具
go get -u github.com/swaggo/swag/cmd/swag - 在入口文件写上项目的简介
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)
}
- 在你代码中处理请求的接口函数（通常位于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.PaySearchst.PayListResponseresponse.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'"`
}
- 生成文档
swag init -g cmd/main.go // -g 指定main.go 的位置， 我这边是在cmd文件中
此时目录中多了docs
./docs
├── docs.go
├── swagger.json
└── swagger.yaml
image.png
- 引入gin-swagger渲染文档数据, 利用条件编译来决定是否编译swagger，因为线上运行时，不需要swagger
image.png
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
}
- 在goland中配置build参数，以便本地调试
image.png
至此就完成了。 如有问题请私信我。
