go学习-使用swagger生成接口文档

1安装 swag 命令

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] --> 路由地址及请求方法

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
执行后会生成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
// 当前文档路径: http://localhost:8080/swagger/index.html

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