swaggo 使用

官方文档

 

本地安装

go install github.com/swaggo/swag/cmd/swag@latest

 

项目依赖包

go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

 

main.go

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"

    _ "jwt/docs"
)

// @title Swagger Example API
// @version 1.0
// @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
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:8080
// @BasePath /api/v1

func main() {

    r := gin.Default()

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

    r.GET("/hello",HandleHello)

    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run(":8080")
}

// HandleHi  @Summary 测试SayHello
// @Description 向你说Hello
// @Tags 我是标签
// @Accept json
// @Param who query string true "人名"
// @Router /hi [get]
func HandleHi(c *gin.Context) {
    c.JSON(http.StatusOK,gin.H{
        "msg":"hello",
    })
}

// HandleHello @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 /hello [get]
func HandleHello(c *gin.Context) {
    c.JSON(http.StatusOK,gin.H{
        "msg":"hello",
    })
}

 

生成或更新swagger文档

swag init

 

运行 gin

go run .

 

查看swagger文档

http://localhost:8080/swagger/index.html

 

TODO: 通过 build tag 控制最后的打包（go build -tags="doc"）