【GO】go-swagger

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 [e-mail]

// @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...

参考资料

中文文档
学习资料