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

目录

• 功能特性
• 安装指南
• 基本安装
• 项目中使用
• 依赖项
• 使用说明
• 基础示例
• 与Gin框架集成
• 核心代码
• 注释解析核心
• 类型定义处理
• Swagger文档生成

Swag是一个强大的Go语言工具，能够将代码中的注释自动转换为符合Swagger 2.0规范的API文档。项目支持多种主流Go Web框架，包括Gin、Echo等，通过简单的代码注释即可生成专业的API文档。

核心价值：

• 自动化文档生成，减少手动编写工作量
• 与Swagger UI无缝集成
• 支持多种Go Web框架
• 丰富的注释功能，支持参数验证、响应模型等

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) {
    // 处理逻辑
}

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            // 是否唯一
}

// 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生成接口文档的方法