Go语言使用swagger生成接口文档的方法

package main

// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService http://swagger.io/terms/

// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 这里写接口服务的host
// @BasePath 这里写base path
func main() {
 r := gin.New()

 // liwenzhou.com ...

 r.Run()
}

// GetPostListHandler2 升级版帖子列表接口
// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamPostList false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponsePostList
// @Router /posts2 [get]
func GetPostListHandler2(c *gin.Context) {
 // GET请求参数(query string)：/api/v1/posts2?page=1&size=10&order=time
 // 初始化结构体时指定初始参数
 p := &models.ParamPostList{
 Page: 1,
 Size: 10,
 Order: models.OrderTime,
 }

 if err := c.ShouldBindQuery(p); err != nil {
 zap.L().Error("GetPostListHandler2 with invalid params", zap.Error(err))
 ResponseError(c, CodeInvalidParam)
 return
 }
 data, err := logic.GetPostListNew(p)
 // 获取数据
 if err != nil {
 zap.L().Error("logic.GetPostList() failed", zap.Error(err))
 ResponseError(c, CodeServerBusy)
 return
 }
 ResponseSuccess(c, data)
 // 返回响应
}

// bluebell/models/params.go

// ParamPostList 获取帖子列表query string参数
type ParamPostList struct {
 CommunityID int64 `json:"community_id" form:"community_id"` // 可以为空
 Page int64 `json:"page" form:"page" example:"1"` // 页码
 Size int64 `json:"size" form:"size" example:"10"` // 每页数据量
 Order string `json:"order" form:"order" example:"score"` // 排序依据
}

// bluebell/controller/docs_models.go

// _ResponsePostList 帖子列表接口响应数据
type _ResponsePostList struct {
 Code ResCode   `json:"code"` // 业务响应状态码
 Message string   `json:"message"` // 提示信息
 Data []*models.ApiPostDetail `json:"data"` // 数据
}

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

swag init

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

import (
 // liwenzhou.com ...

 _ "bluebell/docs" // 千万不要忘了导入把你上一步生成的docs

 gs "github.com/swaggo/gin-swagger"
 "github.com/swaggo/gin-swagger/swaggerFiles"

 "github.com/gin-gonic/gin"
)

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

r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))