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基本类型和自定义类型的映射
  
• 扩展功能：
  
  
  
  • 枚举类型支持
    
  • 字段重命名
    
  • 字段忽略
    
  • 自定义字段类型
    
  
  

安装指南

基本安装

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

复制代码

项目中使用

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

1. swag init

复制代码

依赖项

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

使用说明

基础示例

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

复制代码

与Gin框架集成

1. package main
3. import (
4.     "github.com/gin-gonic/gin"
5.     _ "github.com/swaggo/swag/example/celler/docs"
6.     swaggerFiles "github.com/swaggo/files"
7.     ginSwagger "github.com/swaggo/gin-swagger"
8. )
10. // @title Swagger示例API
11. // @version 1.0
12. // @description 这是一个示例服务器
13. func main() {
14.     r := gin.Default()
15.     r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
16.     r.Run(":8080")
17. }

复制代码

核心代码

注释解析核心

1. // Operation描述单个API操作
2. type Operation struct {
3.     parser              *Parser
4.     codeExampleFilesDir string
5.     spec.Operation
6.     RouterProperties []RouteProperties
7.     State            string
8. }
10. // RouteProperties描述HTTP路由属性
11. type RouteProperties struct {
12.     HTTPMethod string
13.     Path       string
14.     Deprecated bool
15. }

复制代码

类型定义处理

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

复制代码

Swagger文档生成

1. // Spec保存导出的Swagger信息
2. type Spec struct {
3.     Version          string
4.     Host             string
5.     BasePath         string
6.     Schemes          []string
7.     Title            string
8.     Description      string
9.     InfoInstanceName string
10.     SwaggerTemplate  string
11.     LeftDelim        string
12.     RightDelim       string
13. }
15. // ReadDoc将SwaggerTemplate解析为swagger文档
16. func (i *Spec) ReadDoc() string {
17.     // 处理模板和转义字符
18.     tpl := template.New("swagger_info").Funcs(template.FuncMap{
19.         "marshal": func(v interface{}) string {
20.             a, _ := json.Marshal(v)
21.             return string(a)
22.         },
23.         "escape": func(v interface{}) string {
24.             str := strings.ReplaceAll(v.(string), "\t", "\\t")
25.             str = strings.ReplaceAll(str, """, "\\"")
26.             return strings.ReplaceAll(str, "\\\\"", "\\\\\\"")
27.         },
28.     })
29.     // 解析并执行模板
30.     parsed, _ := tpl.Parse(i.SwaggerTemplate)
31.     var doc bytes.Buffer
32.     _ = parsed.Execute(&doc, i)
33.     return doc.String()
34. }

复制代码

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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！