swaggo/swag

これは何？

主な機能

• 01Swagger 2.0の仕様をJSON、YAML、Goのdocsパッケージとして生成します。
• 02Goのハンドラー関数の上に記述したコメントアノテーションでエンドポイントをドキュメント化します。
• 03リクエストパラメーター、レスポンス、ヘッダー、セキュリティ定義、タグに対応します。
• 04structフィールドのタグから、サンプル、バリデーションルール、enumを読み取ります。
• 05Gin、Echo、Fiber、net/http、chiなどのフレームワーク向けミドルウェアを提供します。
• 06アノテーションコメントを整形するswag fmtコマンドを備えています。

ユースケース

• OpenAPIファイルを別途手作業で管理せずに、Go製RESTサービスのAPIドキュメントを生成する。
• GinやEchoのバックエンドで、インタラクティブなSwagger UIページを公開する。
• CIビルド時に、APIドキュメントをハンドラーコードと同期させる。

クイックスタート

1. 1

   Goでswag CLIをインストールする

   go install github.com/swaggo/swag/cmd/swag@latest
2. 2

   GoのソースコードのコメントにAPIアノテーションを追加する

3. 3

   main.goを含むプロジェクトのルートでswag initを実行し、ドキュメントを生成する

   swag init

使う前に知っておきたいこと

• !生成できるのはSwagger 2.0のドキュメントのみで、OpenAPI 3.xには対応していません。
• !Goのコメントにアノテーションを記述する必要があり、変更後はドキュメントを再生成する必要があります。

トピック

よくある質問

swag とは？

Goのソースコードコメントに記述したアノテーションからSwagger 2.0のAPIドキュメントを生成するツールです。 Swagは、ハンドラー関数やstruct定義など、Goコード内の所定の形式で書かれたコメントを解析し、swagger.json、swagger.yaml、docs.goとしてSwagger 2.0のドキュメントを生成します。開発者はハンドラーの上に@Summary、@Param、@Success、@Routerなどのアノテーションを記述し、swag initを実行して仕様を再生成します。

swag は無料で使えますか？ライセンスは？

swag は MIT ライセンスのオープンソースです。商用製品で使う前にライセンス条件を確認してください。

swag は今もメンテナンスされていますか？

半年以内に更新あり。swag の最終コミットは 2026年9月30日 です。

swag は何に使えますか？

OpenAPIファイルを別途手作業で管理せずに、Go製RESTサービスのAPIドキュメントを生成する。 GinやEchoのバックエンドで、インタラクティブなSwagger UIページを公開する。 CIビルド時に、APIドキュメントをハンドラーコードと同期させる。

swag のインストール方法は？

Goでswag CLIをインストールする: go install github.com/swaggo/swag/cmd/swag@latest GoのソースコードのコメントにAPIアノテーションを追加する main.goを含むプロジェクトのルートでswag initを実行し、ドキュメントを生成する: swag init

swag はどこで入手できますか？

ソースコードとインストール手順は GitHub にあります：https://github.com/swaggo/swag