gin配置swagger文档

一、基本准备工作

• 1、安装依赖包

  go get -u github.com/swaggo/swag/cmd/swag
  go get -u github.com/swaggo/gin-swagger
  go get -u github.com/swaggo/files
  

• 2、在根目录上配置swagger的路由文件

    //2.初始化路由
    router := initialize.Routers()
    // 配置swagger
    docs.SwaggerInfo.BasePath = ""
    router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
  

• 3、使用命令生成swagger文件

  swag init
  

二、swagger文档的书写

• 1、在main中全局配置项目说明

  // @title 测试项目
  // @version 1.0 版本
  // @description 简单测试案例 描述
  // @BasePath /api/admin/v1  基础路径
  // @query.collection.format multi
  func main() {
      //2.初始化路由
      router := initialize.Routers()
      // 配置swagger
      docs.SwaggerInfo.BasePath = ""
      router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
  	// 访问地址:http://localhost:9000/swagger/index.html
      // 获取端口号
      const PORT = "9000"
      fmt.Println(PORT + "当前端口")
      fmt.Println(fmt.Sprintf("服务已经启动:localhost:%s", PORT))
      if err := router.Run(fmt.Sprintf(":%s", PORT)); err != nil {
          fmt.Println(fmt.Sprintf("服务启动失败:%s", err.Error()))
      }
  }
  

  

• 2、对于post提交参数的控制层

  // CreateAccountApi
  // @Summary 创建用户
  // @Tags 用户模块
  // @Param accountDto body dto.AccountDto true "入参"
  // @Success 200 string json{"code":"200","data":"","msg":"ok"}
  // @Router /api/v1/admin/account [post]
  func (a Account) CreateAccountApi(ctx *gin.Context) {
  	panic("implement me")
  }
  

  

  自定义结构体

  type AccountDto struct {
  	UserName string `json:"userName" binding:"required"` // 用户名
  	Password string `json:"password" binding:"required"` // 密码
  }
  

• 4、根据id删除数据

  // DeleteAccountByIdApi
  // @Summary 根据id删除账号
  // @Tags 用户模块
  // @Param id path int true "id"
  // @Success 200 string json{"code":"200","data":"","msg":"ok"}
  // @Router /api/v1/admin/account [delete]
  func (a Account) DeleteAccountByIdApi(ctx *gin.Context) {
  	//TODO implement me
  	panic("implement me")
  }
  

• 5、get请求分页获取数据

  // GetAccountPageApi
  // @Summary 分页获取用户
  // @Tags 用户模块
  // @Param pageNumber query int true "pageNumber"
  // @Param pageSize query int true "pageSize"
  // @Success 200 {object} vo.AccountVo
  // @Router /api/v1/admin/account [get]
  func (a Account) GetAccountPageApi(ctx *gin.Context) {
  	utils.Success(ctx, vo.AccountVo{
  		Id:       1,
  		UserName: "李四",
  		Age:      10,
  	})
  	return
  }
  

三、将生成的swagger文件导入到apifox中