Go利用Swag實現(xiàn)將注釋轉(zhuǎn)換為專業(yè)的API文檔

更新時間：2025年06月30日 08:46:20 作者：qife122

Swag是一個將Go語言注釋自動轉(zhuǎn)換為Swagger 2.0文檔的工具,支持多種流行Go Web框架,本文我們就來簡單講講如何使用Swag將簡單的代碼注釋生成專業(yè)的API文檔的吧

功能特性

1.自動文檔生成：通過解析Go代碼中的特殊注釋自動生成Swagger文檔

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

3.豐富的注釋功能：

API基本信息（標題、版本、描述等）
路由定義
參數(shù)描述（路徑參數(shù)、查詢參數(shù)、請求體等）
響應(yīng)模型定義
安全定義（BasicAuth、APIKey、OAuth2等）

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

5.擴展功能：

枚舉類型支持
字段重命名
字段忽略
自定義字段類型

安裝指南

基本安裝

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

項目中使用

在項目中添加Swag注釋

運行命令生成文檔：

swag init

依賴項

Go 1.18+
支持的Web框架（如Gin、Echo等）

使用說明

基礎(chǔ)示例

// @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 這是一個示例服務(wù)器
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保存導(dǎo)出的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 {
    // 處理模板和轉(zhuǎn)義字符
    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, "\\\\\"", "\\\\\\\"")
        },
    })
    // 解析并執(zhí)行模板
    parsed, _ := tpl.Parse(i.SwaggerTemplate)
    var doc bytes.Buffer
    _ = parsed.Execute(&doc, i)
    return doc.String()
}

到此這篇關(guān)于Go利用Swag實現(xiàn)將注釋轉(zhuǎn)換為專業(yè)的API文檔的文章就介紹到這了,更多相關(guān)Go Swag生成API文檔內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: