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

项目标题与描述

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 

项目中使用

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

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智能小助手）
公众号二维码