首页 > 脚本专栏 > Golang > Go Swag生成API文档

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

2025-06-30 08:46:21 作者：qife122

Swag是一个将Go语言注释自动转换为Swagger 2.0文档的工具,支持多种流行Go Web框架,本文我们就来简单讲讲如何使用Swag将简单的代码注释生成专业的API文档的吧

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

与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
    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文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！