go swag

1安装 swag 命令

官网链接：https://github.com/swaggo/swag/blob/master/README_zh-CN.mdhttps://github.com/swaggo/swag/blob/master/README_zh-CN.md

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

2编写注解

服务基础信息（main.go)

// @title swagger使用例子
// @version 1.0
// @description swagger 入门使用例子
// @host localhost:8080 --->这里写接口服务的host
// @BasePath /api/vi -->这里写base path

api信息(controller中各个接口前)

// @summary 接口简介
// @Description 接口描述
// @Accept json --> 可生成的MIME类型，既接收类型
// @Produce json --> 可生成的MIME类型，既响应返回类型
// @Param user body domain.UserStruct "传入参数是struct"
// Success 200 {object} Response --> 成功后返回数据结构
// Failure 400 {object} ResponseError --> 失败后返回数据结构
// Failure 404 {object} ResponseError
// Failure 500 {object} ResponseError
// @Router /check [get] --> 路由地址及请求方法

直接用上面的定义生成swagger文档会报错，把注释去掉就ok

// @summary 获取文章list接口
// @Description 获取文章list接口
// @Tags article
// @Accept json 
// @Produce json 
// @param Authorization header string true "验证参数Bearer和token空格拼接"
// @Param  GetOwnArticleReq body article.GetOwnArticleReq  true "请求""
// @Success 200 {object} article.ArticleListResponse
// @Failure 500 {object} article.ArticleListResponse
// @Router /article/list [get] 

API 注释定义

• param 参数 格式: [ 参数名称 参数类型 数据类型 是否必须 备注 限制属性 ] 空格分割
  @Params userId query string true "用户id" minlength(3) maxlength(100)
  @Params status query integer false "状态：0 1" Enums(0, 1) defualt(0)

参数可用类型 [param type]

query :表示带在 url 之后的参数 get请求
path :path 表示请求路径上得参数 /check{id} 例：@Params id path integer false
header :表示带在 header 信息中得参数
body :表示是一个 raw 数据请求 post请求
formDate:formData 表示是 post 请求的数据

数据可用类型 [data type]

string(string)
integer(int, uint, uint32, uint64)
boolean(bool)
user defined struct

可配置属性

defualt * 参数默认值
maximum number 最大值
mininum number 最小值
maxLength integer 最大长度
minLength integer 最小长度
enums [*] 枚举类型
format string
collectionFormat string query数组分割模式

• security 安全性

success 成功响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]

@Success 200 {object} Response "返回空对象"

failure 失败响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]

@Failure 400 {object} ResponseError

• header 请求头字段 格式: [ 状态码 {数据类型} 数据类型 备注 ]

// @Header 200 {string} Token "qwerty"

• router 路由路径

// @Router /user/{userId} [get]

3生成文档

// 根目录执行
swag init

直接执行swag init 不会生成依赖的结构体 需要手动添加选项：swag init --parseDependency 

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源文件，默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")

执行后会生成docs的文件夹
./docs
├── docs.go
├── swagger.json
└── swagger.yaml

4配置文档路由

在配置路由的文件中添加

import (
     _ "server/docs"  // 这里需要引入本地已生成文档
     ginSwagger "github.com/swaggo/gin-swagger" 
     swaggerFiles "github.com/swaggo/files"
)


func main(){
    ...
    
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}

5启动服务并访问

go run main.go
// 当前文档路径: localhost:swagger/index.html

6每次更新注释后记得 swag init 更新json文件