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

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

swag init

// @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()
}