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

作者：qife

2025-06-29
中国台湾
本文字数：1724 字
阅读完需：约 6 分钟

项目标题与描述

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()}

复制代码

更多精彩内容请关注我的个人公众号公众号（办公 AI 智能小助手）公众号二维码

办公AI智能小助手

发布于: 刚刚阅读数: 2

qife

关注

还未添加个人签名 2021-05-19 加入

还未添加个人简介

发布

暂无评论

创作场景

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

项目标题与描述

功能特性

安装指南

基本安装

项目中使用

依赖项

使用说明

基础示例

与 Gin 框架集成

核心代码

注释解析核心

类型定义处理

Swagger 文档生成

qife

评论