【GO】go-swagger

1. Installation

install

2. Simple use

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

• Swag init is required every time the API related content is modified. Otherwise, the old docs will be used, which is the same as the previous results
• Swag involves cross domain issues. Replace “@ host 172.0.0.1:9090” with “@ host localhost: 9090”, or vice versa; Try in the address bar http://localhost:8899/swagger…
• r. Get (“/ swagger / * any”, ginswagger. Wraphandler (swaggerfiles. Handler)) required
• Link swag interface: http://localhost:8080/swagger…
• In inithandlers() file, you want to import ‘_ “Mycasbin / docs”, otherwise an error will be reported: failed to load spec
• The generated curl, such as curl – x get“ http://localhost:10086/api/test/hello?who=ss “- H” accept: application / JSON “is executed on the terminal, and the effect is the same as that in swagger

Sample

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" [the generated docs files must be imported]
   "fmt"
)


//@ Title swagger example API [name of required application]
//@ version 1.0 [required to provide the version of application 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 [email protected]

// @license. Name Apache 2.0 [required license name for API]
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html 

//@ host localhost: 9999 [consistent with r.run (": 9999")
// @BasePath /wzz

func main() {
   r := gin.Default()
   r. Get ("/ swagger / * any", ginswagger. Wraphandler (swaggerfiles. Handler)) [this sentence must be written]

   hi := r.Group("/wzz/hi")
   {
      hi.GET("/hello", HandleHello)
   }

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

//@ summary test sayhello
//@ description say hello to you
//@ tags test
// @Accept json
//@ param who query string true "person name"
// @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})
}

Terminal test

Test on the command line: (you need to change localhost to 127.0.0.1)

error handling

1.Q: Fatal type error
A: Swag involves cross domain issues. Replace “@ host 172.0.0.1:9090” with “@ host localhost: 9090”, or vice versa; Try in the address bar http://localhost:8899/swagger…

reference material

Chinese documents
Learning materials