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项目中使用
[*]在项目中添加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}
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
SwaggerTemplatestring
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智能小助手）
公众号二维码
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！
页:
[1]