golang, gin-swagger的使用
1、安装swag
go get -u github.com/swaggo/swag/cmd/swag
2、安装gin-swagger
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
3、代码例子
package main
import (
"github.com/gin-gonic/gin"
docs "github.com/go-project-name/docs"
swaggerfiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
"net/http"
)
// @BasePath /api/v1
// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context) {
g.JSON(http.StatusOK,"helloworld")
}
func main() {
r := gin.Default()
docs.SwaggerInfo.BasePath = "/api/v1"
v1 := r.Group("/api/v1")
{
eg := v1.Group("/example")
{
eg.GET("/helloworld",Helloworld)
}
}
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
r.Run(":8080")
}4、访问地址
http://localhost:8080/swagger/index.html
生成doc文档用法(官方说明文档): 运行swag init, 默认会在main.go目录下生成docs文件夹.
swag init -h
NAME:
swag init - Create docs.go
USAGE:
swag init [command options] [arguments...]
OPTIONS:
--generalInfo value, -g value API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
--dir value, -d value API解析目录 (默认: "./")
--exclude value 解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
--propertyStrategy value, -p value 结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
--output value, -o value 文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
--parseVendor 是否解析vendor目录里的go源文件，默认不
--parseDependency 是否解析依赖目录中的go源文件，默认不
--parseDependencyLevel, --pdl 对'--parseDependency'参数进行增强, 是否解析依赖目录中的go源文件, 0 不解析, 1 只解析对象模型, 2 只解析API, 3 对象模型和API都解析 (default: 0)
--markdownFiles value, --md value 指定API的描述信息所使用的markdown文件所在的目录
--generatedTime 是否输出时间到输出文件docs.go的顶部，默认是
--codeExampleFiles value, --cef value 解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
--parseInternal 解析 internal 包中的go文件，默认禁用
--parseDepth value 依赖解析深度 (默认: 100)
--instanceName value 设置文档实例名 (默认: "swagger")模型定义:
type TestModel struct {
// 名称
Name int `json:"name" example:"名称"`
}方法定义:
// test
// @Tags test
// @Summary test
// @Description test
// @Accept application/json
// @Produce application/json
// @Param params body TestModel true "name参数"
// @Success 200 {object} response.Response{requestId=string,code=int,data=TestModel,msg=string} "错误码10101: 系统繁忙，请稍后再试(数据处理失败); 错误码20102: 请求参数错误"
// @Router /test [post]
func (t *Test) Test(c *gin.Context) {
// 逻辑实现...
}
