gin配置swagger文档

news2024/12/28 4:54:30

一、基本准备工作

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
}