环境配置

1、 向您的 API 源代码添加注释，请参阅声明性注释格式。
2、使用以下命令下载Swag for Go：
3、下载依赖包

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

代码中进行配置

1、router.go中配置

import (
   "github.com/swaggo/files"
   "github.com/swaggo/gin-swagger"
   _ "xxxx/docs"
   "github.com/gin-gonic/gin"
)

// 设置swagger路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

2、main.go中配置添加注释：

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @in header

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// 下面注释按照项目实际的地址和路径进行设置
// @host 127.0.0.1:8093 
// @BasePath /api/manage

func main() {
   // 接收参数
   flag.StringVar(&mode, "mode", "server", "运行模式,运行server服务或者执行migrate.")
   flag.StringVar(&confPath, "c", "./configs/config.yaml", "配置文件路径.")
   flag.Parse()

   // 参数合法性校验
   if mode != "server" && mode != "migrate" {
      log.Fatal("run 参数非法: 运行模式只能选择 server 或 migrate")
   }

   // 初始化
   Setup()

   // 根据参数执行对应模式服务
   if mode == "server" {
      runServer()
   } else {
      migrate.MigrateTable()
   }
}

3、在具体的请求方法中添加注释

// List
// @通知信息列表
// @Description List
// @Accept  json
// @Produce json
// @Param   offset     path    int     true        "15"
// @Param   limit     path    int     true        "15"
// @in header
// @Success 200 {string} string    "ok"
// @Router /notice [get]
func List(c *gin.Context) {
   // 分页参数
   offset, limit, err := request.GetPagerParams(c)
   if err != nil {
      response.ParamsError(c, err.Error())
      return
   }
   // 排序条件
   orderExpr, err := request.GetOrderParams(c)
   if err != nil {
      response.ParamsError(c, err.Error())
      return
   }

   // 查询db获取数据
   results := make([]*notice.Notice, 0)
   count, err := model.GetPageListWithSearch(&results, offset, limit, orderExpr, c.Query("search"), nil)

   if err != nil {
      response.BaseError(c, err.Error())
      return
   }

   respData := &RespList{
      List:  make([]*RespItem, len(results)),
      Count: count,
   }
   // 组装返回类型
   for ix, item := range results {
      d := &RespItem{
         ID:        item.ID,
         Source:    item.Source,
         Type:      item.Type,
         Contacts:  item.Contacts,
         Content:   item.Content,
         Result:    item.Result,
         CreatedAt: item.CreatedAt.Format("2006-01-02 15:04:05"),
         UpdatedAt: item.UpdatedAt.Format("2006-01-02 15:04:05"),
      }
      respData.List[ix] = d
   }
   // 返回请求
   response.Success(c, respData)
}

4、执行初始化命令

swag init // 注意，一定要和main.go处于同一级目录

初始化命令，在根目录生成一个docs文件夹，每次注释变更，都需要执行此步骤，开始没有找到swag命令，命令位置在$GOPATH/bin/swag

5、访问接口文档

地址为：http://127.0.0.1:8093/swagger/index.html
接口文档样例：

image.png

image.png