golang-swagger

ペルソナ: Go API ドキュメンテーション エンジニアです。ドキュメントは契約として扱います — 正確で完全なアノテーションは統合バグを防ぎ、Swagger UI を API コンシューマーの信頼できる情報源にします。

モード:

• Build — 新規または既存の Go プロジェクトに Swagger を追加: ツールチェーンをセットアップし、ハンドラにアノテーションを付け、ドキュメントを生成し、UI エンドポイントを配線します。
• Audit — 既存の swagger アノテーションの完全性、正確性、セキュリティ対応状況をレビューします。

セットアップ

Swagger UI を実行するための 3 つのステップ:

swag init                        # generates docs/ with docs.go, swagger.json, swagger.yaml
swag init -g cmd/api/main.go     # if general info is not in main.go
swag fmt                         # format annotation comments (like go fmt)

docs パッケージをインポートしてスペックを登録します。UI だけを配線する場合はブランクインポートを使い、実行時に docs.SwaggerInfo をオーバーライドする必要がある場合は名前付きインポートを使用します:

import _ "yourmodule/docs"          // blank: registers spec, no identifier
import docs "yourmodule/docs"       // named: use when overriding 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))

UI に /swagger/index.html でアクセスします。

動的なホスト/ベースパス (マルチ環境) の場合は、名前付きインポートを使用し、サーブ前にオーバーライドします:

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     Short description of the API.
// @host            localhost:8080
// @BasePath        /api/v1
// @schemes         http https

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

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description Type "Bearer" followed by a space and the JWT token.

オペレーション アノテーション

各ハンドラ関数にアノテーションを付けます。標準的なドキュメンテーション コメント (// FuncName godoc) は swag アノテーションの前に必ず置く必要があります — これは swag fmt のインデント固定点となります。

// ShowAccount godoc
// @Summary      Get account by ID
// @Description  Returns account details for the given ID.
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id      path  int  true  "Account ID"
// @Param        filter  query string false "Optional search filter"
// @Success      200  {object}  model.Account
// @Success      204  "No content"
// @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	マルチパート/フォームフィールド

@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) で 1 回定義し、@Security でエンドポイントごとに適用します。

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

// API key in header
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key

// Basic auth
// @securityDefinitions.basic BasicAuth

// OAuth2 authorization code
// @securityDefinitions.oauth2.authorizationCode OAuth2
// @authorizationUrl https://example.com/oauth/authorize
// @tokenUrl https://example.com/oauth/token
// @scope.read Read access
// @scope.write Write access

エンドポイントに適用:

// @Security Bearer
// @Security OAuth2[read, write]
// @Security BasicAuth && ApiKeyAuth   // AND — both required

構造体タグ

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"`  // excluded from docs
}

タグ	目的
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 からスキーマを導出できず、生成に失敗	本体パラメータは常に名前付き構造体を使用
保護されたルートに @Security がない	Swagger UI にロックアイコンが表示されず、テスターが認証なしでリクエストを送信	認証が必要なすべてのエンドポイントに @Security を適用
一般情報アノテーションを間違ったファイルに配置	swag がそれらをサイレントにスキップし、スペックにタイトル/ホストがない	-g <file> フラグを使用するか、アノテーションを main.go に移動
マップ型で {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 の場合は swag の代わりに grpc-gateway とその OpenAPI ジェネレータを使用。

このスキルは網羅的ではありません。最新の API シグネチャと使用パターンについて、swaggo/swag ドキュメントとコード例を参照してください。Context7 はディスカバリプラットフォームとしてサポートできます。

swag でバグや予期しない動作が発生した場合は、https://github.com/swaggo/swag/issues でイシューをオープンしてください。