快捷導(dǎo)航

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

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

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

Swag是一個(gè)強(qiáng)大的Go語(yǔ)言工具，能夠?qū)⒋a中的注釋自動(dòng)轉(zhuǎn)換為符合Swagger 2.0規(guī)范的API文檔。項(xiàng)目支持多種主流Go Web框架，包括Gin、Echo等，通過(guò)簡(jiǎn)單的代碼注釋即可生成專(zhuān)業(yè)的API文檔。

核心價(jià)值：

自動(dòng)化文檔生成，減少手動(dòng)編寫(xiě)工作量
與Swagger UI無(wú)縫集成
支持多種Go Web框架
豐富的注釋功能，支持參數(shù)驗(yàn)證、響應(yīng)模型等

功能特性

1.自動(dòng)文檔生成：通過(guò)解析Go代碼中的特殊注釋自動(dòng)生成Swagger文檔

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

3.豐富的注釋功能：

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

4.類(lèi)型安全：支持Go基本類(lèi)型和自定義類(lèi)型的映射

5.擴(kuò)展功能：

枚舉類(lèi)型支持
字段重命名
字段忽略
自定義字段類(lèi)型

安裝指南

基本安裝

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

項(xiàng)目中使用

在項(xiàng)目中添加Swag注釋

運(yùn)行命令生成文檔：

swag init

依賴(lài)項(xiàng)

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

使用說(shuō)明

基礎(chǔ)示例

// @Summary 獲取用戶信息
// @Description 通過(guò)用戶ID獲取用戶詳細(xì)信息
// @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 這是一個(gè)示例服務(wù)器
func main() {
    r := gin.Default()
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}

核心代碼

注釋解析核心

// Operation描述單個(gè)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
}

類(lèi)型定義處理

// TypeSpecDef包含類(lèi)型定義的完整信息
type TypeSpecDef struct {
    File      *ast.File       // 包含TypeSpec的ast文件
    TypeSpec  *ast.TypeSpec   // 類(lèi)型定義
    Enums     []EnumValue     // 枚舉值
    PkgPath   string          // 包路徑
    ParentSpec ast.Decl       // 父聲明
    SchemaName string         // Schema名稱(chēng)
    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實(shí)現(xiàn)將注釋轉(zhuǎn)換為專(zhuān)業(yè)的API文檔的文章就介紹到這了,更多相關(guān)Go Swag生成API文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: