关于golang:GOgoswagger

1. 装置

装置

2. 简略应用

main.go

package main

import (
   "github.com/gin-gonic/gin"
   "swagger_study/handler"
)


func main(){
   var server  *gin.Engine
   server =gin.Default()
   handler.InitHandlers(server)
   server.Run()}

handler/api.go

package handler

import (
   "github.com/gin-gonic/gin"
   ginSwagger "github.com/swaggo/gin-swagger"
   "github.com/swaggo/gin-swagger/swaggerFiles"
   "swagger_study/handler/test"
   _ "swagger_study/docs"
)

// @title SwaggerTest Server
// @version 0.1
// @description SwaggerTest Server
// @in header
// @license.name Apache 2.0
// @host 127.0.0.1:8080
// @BasePath /api
func InitHandlers(server  *gin.Engine) {server.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

   //Test API
   appApi := server.Group("/api/test")
   {appApi.GET("/hi",test.HandleHi)
   }
}

handler/test/test.go

// @title SwaggerTest Server
// @version 0.1
// @description SwaggerTest Server
// @in header
// @license.name Apache 2.0
// @host 127.0.0.1:8080
// @BasePath /api
func InitHandlers(server  *gin.Engine) {server.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

   //Test API
   appApi := server.Group("/api/test")
   {appApi.GET("/hi",test.HandleHi)
   }
}

Makefile

gen:
   swag init --generalInfo  handler/api.go

Tips

• 每次批改与 API 无关的内容都须要 swag init，否则会采纳旧的 docs，即跟之前的后果一样
• swag 波及跨域问题，用“@host localhost:9090”替换“@host 172.0.0.1:9090”，或者反之；在地址栏尝试 http://localhost:8899/swagger…
• r.GET(“/swagger/*any”, ginSwagger.WrapHandler(swaggerFiles.Handler)) 必写
• 链接 swag 界面：http://localhost:8080/swagger…
• 在 InitHandlers() 文件要导入‘_”mycasbin/docs”’，否则会报错：Failed to load spec. 参考链接
• 可将产生的 curl, 如 curl -X GET “http://localhost:10086/api/test/hello?who=ss” -H “accept: application/json” 在终端执行，成果与 swagger 中的雷同

样例

package main

import (
   "archive/zip"
   "github.com/gin-gonic/gin"
   "io"
   "os"
   "path/filepath"
   ginSwagger "github.com/swaggo/gin-swagger"
   "github.com/swaggo/gin-swagger/swaggerFiles"
   "net/http"
   _ "myswag/docs"【产生的 docs 文件肯定要导入】"fmt"
)


// @title Swagger Example API【必填 应用程序的名称】// @version 1.0【必填 提供应用程序 API 的版本】// @description This is a sample server celler server.
// @termsOfService https://www.topgoer.com

// @contact.name www.topgoer.com
// @contact.url https://www.topgoer.com
// @contact.email me@razeen.me

// @license.name Apache 2.0【必填 用于 API 的许可证名称】// @license.url http://www.apache.org/licenses/LICENSE-2.0.html 

// @host localhost:9999【与 r.Run(":9999")要统一】// @BasePath /wzz

func main() {r := gin.Default()
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))【此句肯定要写】hi := r.Group("/wzz/hi")
   {hi.GET("/hello", HandleHello)
   }

   nihao := r.Group("/wzz/load")
   {nihao.POST("/login", HandleLogin)
   }
   r.Run(":9999")
}

// @Summary 测试 SayHello
// @Description 向你说 Hello
// @Tags 测试
// @Accept json
// @Param who query string true "人名"
// @Success 200 {string} string "{"msg":"hello Razeen"}"
// @Failure 400 {string} string "{"msg":"who are you"}"
// @Router /hi/hello [get]
func HandleHello(c *gin.Context) {who := c.Query("who")

   if who == "" {c.JSON(http.StatusBadRequest, gin.H{"msg": "who are u?"})
      return
   }
   c.JSON(http.StatusOK, gin.H{"msg": "hello" + who})
}

终端测试

在命令行测试：(须要将 localhost 改为 127.0.0.1)

错误处理

1.Q: Fatal type error
A:swag 波及跨域问题，用“@host localhost:9090”替换“@host 172.0.0.1:9090”, 或者反之；在地址栏尝试 http://localhost:8899/swagger…

参考资料

中文文档
学习材料