登录/ 注册
 找回密码
 立即注册
关闭

CSDN热搜

程序园 精品问答 技术交流 资源下载
返回列表 发新帖
首页 › 业界区 › 业界 ›Swag - 将Go注释转换为Swagger文档的强大工具 ...

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

韶又彤 2025-6-29 06:55:05
项目标题与描述

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


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

使用道具 举报
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册
发帖
韶又彤
2025-6-29 06:55:05

0

粉丝关注

10

主题发布

板块介绍填写区域，请于后台编辑
微信扫一扫