swagger (GO) API文档工具入门

swaggo
swagger

安装 swag 命令

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

编写注释

服务基础信息

// @title swagger使用例子
// @version 1.0
// @description swagger 入门使用例子
func main(){
    r := gin.Default()
    r.GET("/check", connectCheck)
    ...
}

api信息

type Response struct{
    Code uint32 `json:"code"`
    Message uint32 `json:"message"`
    Data interface{} `json:"data"`
}

type ResponseError struct{
    Code uint32 `json:"code"`
    Message uint32 `json:"message"`
}

// @summary 服务连接校验 --> 接口简介
// @Description 服务初始连接测试 --> 接口描述
// @Accept json   --> 接收类型
// @Produce json  --> 返回类型
// Success 200 {object} Response --> 成功后返回数据结构
// Failure 400 {object} ResponseError --> 失败后返回数据结构
// Failure 404 {object} ResponseError
// Failure 500 {object} ResponseError
// @Router /check [get] --> 路由地址及请求方法
func connectCheck(c *gin.Context){
    res := Response{ Code: 1001, Message: "OK", Data: "connect success !!!"}
    c.JSON(http.StatusOK, res)
}

生成文档

// 根目录执行
swag init

配置文档路由

import (
     ...
     _ "go-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")
}

启动服务并访问

go run main.go

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

API 注释定义

summary 简介 // @Summary 简介
accept 可使用的MIME类型 // @Accept json
produce 可生成的MIME类型，既响应返回类型 // @Produce json // @Produce png 可设置多条
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
  - path
  - header
  - body
  - formDate
- 数据可用类型 [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]
x-name 扩展字段 type Account struct { ID string `json:"id" extensions:"x-nullable,x-abc=def"` // 扩展字段必须以"x-"开头 }

结构体描述

example 例子

type User struct{
  ID int `json:"id" example:"232323"`
  Name string `json:"name" example:"Coco" `
}

限制属性 type User struct{ ID int `json:"id" minLength:"3" maxLength:"100"` }
swaggerignore 排除字段 type Account struct { ID string `json:"id"` Name string `json:"name"` Ignored int `swaggerignore:"true"` // 排除Ignored字段 }
重命名 type Resp struct { Code int }//@name Response 必须放在结构体末尾

注意事项

多字段定义时不能跨字段 // @Accept json // @Produce json // @param id query string false "用户id" default("") minlength(3) maxlength(100) // @Produce json 这里将报错
修改定义后需要重新执行，生成命令并重启服务
路由配置时，引入文档