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 这里将报错
• 修改定义后需要重新执行，生成命令并重启服务
• 路由配置时，引入文档