[go-每日一库]golang swagger自动生成api文档

代码结构

.
+--- docs
|   +--- docs.go
|   +--- swagger.json
|   +--- swagger.yaml
+--- go.mod
+--- go.sum
+--- main.go
+--- router
|   +--- router.go

router.go

package router
 
import (
	"github.com/gin-gonic/gin"
	ginSwagger "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	_ "go-gin-swagger/docs"
	"net/http"
)
 
func NewRouter() *gin.Engine {
	server := gin.Default()
 
	server.POST("login", login)
	server.GET("index", index)
	// add swagger
	url := ginSwagger.URL("http://localhost:8000/swagger/doc.json")
	server.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
 
	return server
}
 
// @Summary 登录-login
// @Produce json
// @Param username body string true "username"
// @Param password body string true "password" minLength(8)
// @Success 200
// @Failure 400
// @Router /login [post]
func login(ctx *gin.Context)  {
	var user User
	ctx.ShouldBindJSON(&user)
	ctx.JSON(http.StatusOK, gin.H{"user": user.Username, "password": user.Password, "code": 0})
}
 
// @Summary 首页-index
// @Produce json
// @Success 200
// @Failure 400
// @Router /index [get]
func index(ctx *gin.Context)  {
	ctx.JSON(http.StatusOK, gin.H{"msg": "index page", "code": 0})
}
 
type User struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

main.go

package main
 
import (
	. "go-gin-swagger/router"
)
 
// @title gin-swagger
// @version 1.0
// @description Go-gin-swagger
// @termsOfService http://localhost:8080
func main()  {
	r := NewRouter()
	r.Run(":8080")
}

go.mod

module go-gin-swagger
 
go 1.16
 
require (
	github.com/gin-gonic/gin v1.8.1
	github.com/go-playground/validator/v10 v10.11.0 // indirect
	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
	github.com/pelletier/go-toml/v2 v2.0.2 // indirect
	github.com/swaggo/gin-swagger v1.4.3
	github.com/swaggo/swag v1.8.2
	golang.org/x/crypto v0.0.0-20220525230936-793ad666bf5e // indirect
	golang.org/x/net v0.0.0-20220607020251-c690dde0001d // indirect
	golang.org/x/sys v0.0.0-20220608164250-635b8c9b7f68 // indirect
)
 
replace go-gin-swagger => ../go-gin-swagger

参考：

• 基于golang的swagger超贴心、超详细使用指南
• 教你如何使用go-swagger文档