Go|gin quickly use swagger

install

go get -u github.com/swaggo/swag/cmd/swag

Check Their own GOPATH Is it in the environment variable . It can be done by go env see

function

swag init

Will be generated under the directory docs Folder

│  go.mod
│  go.sum
│  main.exe
│  main.go
│
├─docs
│      docs.go
│      swagger.json
│      swagger.yaml

Example

package main

import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	swaggerFiles "github.com/swaggo/files"
	_ "hello/docs" //  Here, you need to import the local generated document 
	"net/http"
)

// @title  Liaoshengping blog  // @version 1.0 // @description swagger  Getting started with examples  func main() {
    
	r := gin.Default() r.GET("/ping", func(c *gin.Context) {
    
		c.JSON(200, gin.H{
    
			"message": "pong",
		})
	})
	r.GET("/get", Get)
	r.POST("/post", Post)
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	//r.GET("/swagger/*any", handleReDoc)
	r.Run() // listen and serve on 0.0.0.0:8080
}

type Response struct{
    
	Code uint32 `json:"code"` Message uint32 `json:"message" description:" describe "` Data interface{
    } `json:"data"`
}

type Requests struct{
    
	Code uint32 `json:"code"` Message uint32 `json:"message"` Data interface{
    } `json:"data"`
}

type ResponseError struct{
    
	Code uint32 `json:"code"`
	Message uint32 `json:"message"`
}

// @title Swagger Example API // @version 1.0 // @description This is a sample server celler server. // @termsOfService http://swagger.io/terms/ // @contact.name API Support // @contact.url http://www.swagger.io/support // @contact.email [email protected] // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @securityDefinitions.basic BasicAuth // @Summary GET Example of a request  // @Schemes // @Description GET Example description of the request  // @Tags  Request example  // @Param id query int true "Account ID" // @Accept json // @Produce json // @Success 200  {
    object}  Response
// @Router /get [get] func Get(c *gin.Context){
    
	res := Response{
     Code: 1001, Message: 1, Data: "connect success !!!"}
	c.JSON(http.StatusOK, res)
}


// @Summary POST Example of a request  // @Description POST Example description of the request  // @Tags  Request example  // @Param body body Requests true "JSON data " // @Accept json // @Produce json // @Success 200  {
    object}  Response       -->   The data structure is returned after success 
// @Failure 400  {
    object}  ResponseError  -->   The data structure is returned after failure 
// @Router /post [post] func Post(c *gin.Context){
    
	res := Response{
     Code: 1001, Message: 1, Data: "connect success !!!"}
	c.JSON(http.StatusOK, res)
}

go run main.go

Generate a GET request .

Format notes

swag fmt

Parameters

Add header information

// @param Authorization header string true " Verify parameters Bearer and token Space splicing "

File upload example

// @Param file formData file true "this is a test file"

Request mode

// @Accept multipart/form-data

Ignore fields

type Ignored struct {
    
	Field5 string `swaggerignore:"true"`
}

Rename the model

type Resp struct {
    
    Code int
}//@name Response

Use enumerated

// @Param enumstring query string false "string enums" Enums(A, B, C)
// @Param enumint query int false "int enums" Enums(1, 2, 3)
// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)

String limit length

// @Param string query string false "string valid" minlength(5) maxlength(10)
// @Param int query int false "int valid" minimum(1) maximum(10)

verification

// @Security ApiKeyAuth
// @Security OAuth2Implicit[admin, write]

swag Return to tool

// Auth godoc
// @Summary Auth admin
// @Description get admin info
// @Tags accounts,admin
// @Accept json
// @Produce json
// @Success 200 {object} model.Admin
// @Failure 400 {object} httputil.HTTPError
// @Failure 401 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Security ApiKeyAuth
// @Router /admin/auth [post]
func (c *Controller) Auth(ctx *gin.Context) {
    
	authHeader := ctx.GetHeader("Authorization")
	if len(authHeader) == 0 {
    
		httputil.NewError(ctx, http.StatusBadRequest, errors.New("please set Header Authorization"))
		return
	}
	if authHeader != "admin" {
    
		httputil.NewError(ctx, http.StatusUnauthorized, fmt.Errorf("this user isn't authorized to operation key=%s expected=admin", authHeader))
		return
	}
	admin := model.Admin{
    
		ID:   1,
		Name: "admin",
	}
	ctx.JSON(http.StatusOK, admin)
}

• Data example

type Message struct {
    
	Message string `json:"message" example:"message"`
}

• Support markdown

// @Description |  Parameters  |  explain  | remarks |
// @Description | :-----: | :----: | :----: |
// @Description |  Parameters  |  explain  |  Assad  |