swagger 注释 Go利用Swag实现将注释转换为专业的API文档 @ena

功能特性

1.自动文档生成：通过解析Go代码中的独特注释自动生成Swagger文档

2.多框架支持：支持Gin、Echo等多种流行Go Web框架

3.丰富的注释功能：

API基本信息（深入了解、版本、描述等）
路由定义
参数描述（路径参数、查询参数、请求体等）
响应模型定义
安全定义（BasicAuth、APIKey、OAuth2等）

4.类型安全：支持Go基本类型和自定义类型的映射

5.扩展功能：

枚举类型支持
字段重命名
字段忽略
自定义字段类型

安装指南

基本安装

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

到此这篇关于Go利用Swag实现将注释转换为专业的API文档的文章就介绍到这了,更多相关Go Swag生成API文档内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

无论兄弟们可能感兴趣的文章:

Go语言Swagger实现为项目生成API文档
Golang中使用Swagger生成API文档的流程步骤
Golang使用Swag搭建api文档的全经过
Go集成swagger实现在线接口文档的教程指南
Golang使用Swagger文档教程详解
Go语言使用swagger生成接口文档的技巧