golang-swagger

役割: Go API ドキュメントのエンジニアです。ドキュメントを契約として扱います。正確で完全な注釈は統合時のバグを防ぎ、Swagger UIをAPI利用者にとっての信頼できる情報源にします。

モード:

• 構築 — 新規または既存のGoプロジェクトにSwaggerを追加します。ツールチェーンをセットアップし、ハンドラーに注釈を付け、ドキュメントを生成し、UIエンドポイントを接続します。
• 監査 — 既存のSwagger注釈の完全性、正確性、セキュリティ対応を確認します。

依存関係:

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

セットアップ

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))

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

// @contact.name    API Support
// @contact.email   [email protected]
// @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）で一度定義し、各エンドポイントに @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 からスキーマを導出できず、生成に失敗します	body パラメーターには必ず名前付き構造体を使用します
保護されたルートに @Security がない	Swagger UI に鍵アイコンが表示されず、テスターが認証なしでリクエストを送信します	認証が必要なすべてのエンドポイントに @Security を指定します
一般情報のアノテーションを誤ったファイルに記述している	swag がアノテーションを黙ってスキップし、仕様にタイトルやホストが設定されません	-g <file> フラグを使用するか、アノテーションを main.go に移します
map 型に {object} を使用している	swag は補助情報なしでは map[string]any のスキーマを生成できません	名前付き構造体を使用するか、swaggertype でアノテーションを付けます
複数語の @Tags を引用符で囲んでいない	タグがスペースで分割され、グループ分けが不正になります	スペースを含むタグは引用符で囲みます：@Tags "user accounts"

関連項目

• → 本番環境で Swagger UI エンドポイントを保護する方法（無効化するか、認証ミドルウェアで制限する方法）については、samber/cc-skills-golang@golang-security を参照してください。
• → gRPC については samber/cc-skills-golang@golang-grpc を参照してください。swag の代わりに、独自の OpenAPI ジェネレーターを備えた grpc-gateway を使用します。

このスキルは網羅的なものではありません。最新の API シグネチャと使用パターンについては、swaggo/swag のドキュメントとコード例を参照してください。

• Go パッケージのドキュメント、シンボル、バージョン、インポーター、既知の脆弱性については、→ samber/cc-skills-golang@golang-pkg-go-dev スキル（godig）を参照してください。Go パッケージに関する情報では Context7 よりこちらを優先します。
• 自分のコード内でこのライブラリの使われ方（定義、呼び出し箇所、診断情報）を調べるには、→ samber/cc-skills-golang@golang-gopls スキル（gopls）を参照してください。
• pkg.go.dev にインデックスされていないドキュメントについては、引き続き Context7 を代替手段として利用できます。

swag でバグや予期しない動作が発生した場合は、https://github.com/swaggo/swag/issues で issue を作成してください。