AI Skills
golang-swagger

golang-swagger

熱門

使用 swaggo/swag 在 Golang 中生成 OpenAPI/Swagger 文件 — 註解註釋 (@Summary, @Param, @Success, @Router, @Security)、swag init 程式碼生成、框架整合 (gin, echo, fiber, chi, net/http)、安全性定義 (Bearer/JWT, OAuth2, API key) 以及結構標籤 (swaggertype, enums, example, swaggerignore)。適用於在 Go 專案中新增或維護 Swagger/OpenAPI 文件，或當程式碼匯入 github.com/swaggo/swag、github.com/swaggo/gin-swagger、github.com/swaggo/echo-swagger、github.com/swaggo/http-swagger 或 github.com/swaggo/files 時。

2261星標
150分支
更新於 2026/6/6
獲取技能源代碼

相關技能

msstore-cli3.7萬site-architecture3.4萬pnpm5444
SKILL.md
readonlyread-only
name
golang-swagger
description

使用 swaggo/swag 在 Golang 中生成 OpenAPI/Swagger 文件 — 註解註釋 (@Summary, @Param, @Success, @Router, @Security)、swag init 程式碼生成、框架整合 (gin, echo, fiber, chi, net/http)、安全性定義 (Bearer/JWT, OAuth2, API key) 以及結構標籤 (swaggertype, enums, example, swaggerignore)。適用於在 Go 專案中新增或維護 Swagger/OpenAPI 文件，或當程式碼匯入 github.com/swaggo/swag、github.com/swaggo/gin-swagger、github.com/swaggo/echo-swagger、github.com/swaggo/http-swagger 或 github.com/swaggo/files 時。

角色： 你是一位 Go API 文件工程師。你將文件視為合約 — 準確、完整的註解可以防止整合錯誤，並讓 Swagger UI 成為 API 使用者的唯一真相來源。

模式：

  • 建置 — 為新的或現有的 Go 專案加入 Swagger：設定工具鏈、註解處理器、生成文件、連接 UI 端點。
  • 稽核 — 檢視現有的 swagger 註解，確保完整性、正確性及安全性涵蓋範圍。

相依套件：

  • swag：go install github.com/swaggo/swag/cmd/swag@latest

設定

三個步驟讓 Swagger UI 運作：

swag init                        # 生成 docs/ 目錄，包含 docs.go、swagger.json、swagger.yaml
swag init -g cmd/api/main.go     # 如果通用資訊不在 main.go 中
swag fmt                         # 格式化註解註釋（類似 go fmt）

匯入 docs 套件以註冊規格。如果只需要連接 UI，使用空白匯入；如果需要在執行時期覆寫 docs.SwaggerInfo，則使用具名匯入：

import _ "yourmodule/docs"          // 空白：註冊規格，無識別字
import docs "yourmodule/docs"       // 具名：覆寫 SwaggerInfo 時使用

連接 UI 端點 — 選擇你的框架：

// Gin
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

// Echo
e.GET("/swagger/*", echoSwagger.WrapHandler)

// Fiber
app.Get("/swagger/*", fiberSwagger.WrapHandler(swaggerFiles.Handler))

// net/http
mux.Handle("/swagger/", httpSwagger.Handler(swaggerFiles.Handler))

// Chi
r.Get("/swagger/*", httpSwagger.Handler(swaggerFiles.Handler))

在 /swagger/index.html 存取 UI。

對於動態主機/基礎路徑（多環境），使用具名匯入並在提供服務前覆寫：

import docs "yourmodule/docs"

docs.SwaggerInfo.Host     = os.Getenv("API_HOST")
docs.SwaggerInfo.BasePath = "/api/v1"

完整 CLI 參考

通用 API 資訊

放在 main.go（或透過 -g 傳入的檔案）中。這些註解定義了頂層規格：

// @title           My API
// @version         1.0
// @description     API 的簡短說明。
// @host            localhost:8080
// @BasePath        /api/v1
// @schemes         http https

// @contact.name    API 支援
// @contact.email   support@example.com
// @license.name    Apache 2.0

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description 輸入 "Bearer" 後接空格和 JWT token。

操作註解

為每個處理器函式加上註解。標準的 doc 註解（// FuncName godoc）必須在 swag 註解之前 — 它為 swag fmt 提供縮排錨點。

// ShowAccount godoc
// @Summary      依 ID 取得帳號
// @Description  回傳指定 ID 的帳號詳細資料。
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id      path  int  true  "帳號 ID"
// @Param        filter  query string false "可選的搜尋篩選條件"
// @Success      200  {object}  model.Account
// @Success      204  "無內容"
// @Failure      400  {object}  api.ErrorResponse
// @Failure      404  {object}  api.ErrorResponse
// @Router       /accounts/{id} [get]
// @Security     Bearer
func ShowAccount(c *gin.Context) {}

@Param 格式：@Param <name> <in> <type> <required> "<description>" [attributes]

<in> 用法
path URL 路徑區段（/users/{id}）
query URL 查詢字串（?filter=x）
body 請求主體 — 型別必須是結構
header HTTP 標頭
formData Multipart/form 欄位

@Param 的可選屬性：default(v)、minimum(n)、maximum(n)、minLength(n)、maxLength(n)、Enums(a,b,c)、example(v)、collectionFormat(multi)。

@Success/@Failure 格式：@Success <code> {<kind>} <type> "<description>"

<kind> 使用時機
{object} 單一結構
{array} 結構切片
string / integer 基本型別

泛型（swag v2）：@Success 200 {object} api.Response[model.User]

巢狀組合：@Success 200 {object} api.Response{data=model.User}

安全性定義

在 API 層級（main.go）定義一次，透過 @Security 套用到每個端點。

// Bearer / JWT
// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization

// API key 在標頭中
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key

// Basic 認證
// @securityDefinitions.basic BasicAuth

// OAuth2 授權碼
// @securityDefinitions.oauth2.authorizationCode OAuth2
// @authorizationUrl https://example.com/oauth/authorize
// @tokenUrl https://example.com/oauth/token
// @scope.read 讀取權限
// @scope.write 寫入權限

套用到端點：

// @Security Bearer
// @Security OAuth2[read, write]
// @Security BasicAuth && ApiKeyAuth   // AND — 兩者都需要

結構標籤

在不改變 Go 型別的情況下豐富模型：

type CreateUserRequest struct {
    Name   string `json:"name" example:"Jane Doe" minLength:"2" maxLength:"100"`
    Role   string `json:"role" enums:"admin,user,guest" example:"user"`
    Age    int    `json:"age" minimum:"18" maximum:"120"`
    Avatar []byte `json:"avatar" swaggertype:"string" format:"base64"`
    Secret string `json:"-" swaggerignore:"true"`  // 從文件中排除
}
標籤 用途
example 在 Swagger UI 中顯示的範例值
enums 逗號分隔的允許值
swaggertype 覆寫偵測到的型別（例如 time.Time 使用 "primitive,integer"）
swaggerignore:"true" 從生成的結構中排除欄位
extensions 加入 OpenAPI 擴充：extensions:"x-nullable,x-deprecated=true"

常見錯誤

錯誤 為什麼會壞掉 修正
缺少 _ "yourmodule/docs" 匯入 結構未註冊；UI 載入空白 在 main.go 或伺服器初始化中加入空白匯入
程式碼變更後 docs/ 未更新 文件與實作脫節；使用者拿到錯誤的結構 每次註解變更後重新執行 swag init
@Param body 使用基本型別 swag 無法從 string 推導結構；生成失敗 對 body 參數一律使用具名結構
受保護的路由沒有 @Security Swagger UI 不顯示鎖頭圖示；測試者發送未認證請求 對每個需要認證的端點套用 @Security
通用資訊註解放在錯誤的檔案 swag 會靜默跳過；規格沒有標題/主機 使用 -g <file> 旗標或將註解移到 main.go
對 map 型別使用 {object} swag 無法為 map[string]any 生成結構，除非有輔助 使用具名結構或使用 swaggertype 註解
多字 @Tags 沒有引號 標籤會依空格分割，產生錯誤的分組 對包含空格的標籤加上引號：@Tags "user accounts"

交叉參考

  • → 參見 samber/cc-skills-golang@golang-security 了解如何在生產環境中保護 Swagger UI 端點（停用或使用認證中介軟體）。
  • → 參見 samber/cc-skills-golang@golang-grpc 了解 gRPC — 使用 grpc-gateway 及其自己的 OpenAPI 生成器，而非 swag。

此技能並非詳盡無遺。請參考 swaggo/swag 文件與程式碼範例，以取得最新的 API 簽章與使用模式。Context7 可作為探索平台提供協助。如需 Go 套件文件、版本、符號及已知漏洞，→ 參見 samber/cc-skills-golang@golang-pkg-go-dev 技能。

如果你在 swag 中遇到錯誤或非預期行為，請在 https://github.com/swaggo/swag/issues 開啟問題。