Swag - 将Go注释转换为Swagger文档的强大工具

爱古丽

于 2025-07-05 04:44:58 发布

阅读量10

点赞数

文章标签： golang 开发语言后端

项目标题与描述

Swag是一个强大的Go语言工具，能够将代码中的注释自动转换为符合Swagger 2.0规范的API文档。项目支持多种主流Go Web框架，包括Gin、Echo等，通过简单的代码注释即可生成专业的API文档。

核心价值：

自动化文档生成，减少手动编写工作量
与Swagger UI无缝集成
支持多种Go Web框架
丰富的注释功能，支持参数验证、响应模型等

功能特性

自动文档生成：通过解析Go代码中的特殊注释自动生成Swagger文档
多框架支持：支持Gin、Echo等多种流行Go Web框架
丰富的注释功能：
- API基本信息（标题、版本、描述等）
- 路由定义
- 参数描述（路径参数、查询参数、请求体等）
- 响应模型定义
- 安全定义（BasicAuth、APIKey、OAuth2等）
类型安全：支持Go基本类型和自定义类型的映射
扩展功能：
- 枚举类型支持
- 字段重命名
- 字段忽略
- 自定义字段类型

安装指南

基本安装

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

项目中使用

在项目中添加Swag注释
运行命令生成文档：

swag init

依赖项

Go 1.18+
支持的Web框架（如Gin、Echo等）

使用说明

基础示例

// @Summary 获取用户信息
// @Description 通过用户ID获取用户详细信息
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} model.User
// @Failure 400 {object} web.APIError
// @Failure 404 {object} web.APIError
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // 处理逻辑
}

与Gin框架集成

package main

import (
    "github.com/gin-gonic/gin"
    _ "github.com/swaggo/swag/example/celler/docs"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

// @title Swagger示例API
// @version 1.0
// @description 这是一个示例服务器
func main() {
    r := gin.Default()
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}

核心代码

注释解析核心

// Operation描述单个API操作
type Operation struct {
    parser              *Parser
    codeExampleFilesDir string
    spec.Operation
    RouterProperties []RouteProperties
    State            string
}

// RouteProperties描述HTTP路由属性
type RouteProperties struct {
    HTTPMethod string
    Path       string
    Deprecated bool
}

类型定义处理

// TypeSpecDef包含类型定义的完整信息
type TypeSpecDef struct {
    File      *ast.File       // 包含TypeSpec的ast文件
    TypeSpec  *ast.TypeSpec   // 类型定义
    Enums     []EnumValue     // 枚举值
    PkgPath   string          // 包路径
    ParentSpec ast.Decl       // 父声明
    SchemaName string         // Schema名称
    NotUnique bool            // 是否唯一
}

Swagger文档生成

// Spec保存导出的Swagger信息
type Spec struct {
    Version          string
    Host             string
    BasePath         string
    Schemes          []string
    Title            string
    Description      string
    InfoInstanceName string
    SwaggerTemplate  string
    LeftDelim        string
    RightDelim       string
}

// ReadDoc将SwaggerTemplate解析为swagger文档
func (i *Spec) ReadDoc() string {
    // 处理模板和转义字符
    tpl := template.New("swagger_info").Funcs(template.FuncMap{
        "marshal": func(v interface{}) string {
            a, _ := json.Marshal(v)
            return string(a)
        },
        "escape": func(v interface{}) string {
            str := strings.ReplaceAll(v.(string), "\t", "\\t")
            str = strings.ReplaceAll(str, "\"", "\\\"")
            return strings.ReplaceAll(str, "\\\\\"", "\\\\\\\"")
        },
    })
    // 解析并执行模板
    parsed, _ := tpl.Parse(i.SwaggerTemplate)
    var doc bytes.Buffer
    _ = parsed.Execute(&doc, i)
    return doc.String()
}