【Go/Gin】Swaggoでunknown field LeftDelimエラーが出た時の原因と解決策

Go言語のWebフレームワークGinでAPIを開発していると、APIドキュメントを自動生成するためにSwaggoを導入するケースは多いですよね。

しかし、開発環境のセットアップやライブラリのアップデート時に、こんなエラーに遭遇したことはありませんか？

# github.com/your-project/docs
docs/docs.go:411:2: unknown field LeftDelim in struct literal of type "github.com/swaggo/swag".Spec
docs/docs.go:412:2: unknown field RightDelim in struct literal of type "github.com/swaggo/swag".Spec

このエラー、Swaggoの仕組みを理解すると原因は単純なのですが、たまにしか発生しないため「あれ、前はどうやって直したんだっけ？」と忘れがちなエラーでもあります。

今回はこのエラーの原因を深掘りし、明確な解決策を解説します。

---

なぜこのエラーが起きるのか？

結論から言うと、このエラーはSwag CLIツールと、プロジェクトが依存しているswagライブラリのバージョンが不一致であることが原因です。

Swaggoは2つの要素で構成されています。

1. Swag CLI (swagコマンド)

   • // @Summary のような形式で書かれたコメントを解析し、APIドキュメントのGoファイル(docs/docs.go)を生成するためのコマンドラインツールです。
   • go install github.com/swaggo/swag/cmd/swag@latest のようにしてインストールします。

2. github.com/swaggo/swag ライブラリ

   • 生成されたdocs/docs.goから実際にドキュメントの情報を読み込み、APIサーバーに組み込むためのライブラリです。
   • こちらはプロジェクトのgo.modファイルで管理されます。

エラーメッセージにある LeftDelim や RightDelim は、swagライブラリの古いバージョンで使われていたフィールドです。

つまり、以下のような状況でエラーが発生します。

1. 開発者は最新版のswagコマンド (swag init) を実行する。
2. 最新版のswagコマンドは、最新のライブラリ仕様に合わせたdocs/docs.goを生成する。このコードには、もはやLeftDelimのような古いフィールドは含まれていない。
3. しかし、プロジェクトのgo.modで指定されているgithub.com/swaggo/swagライブラリのバージョンが古いままになっている。
4. go build を実行すると、古いバージョンのライブラリは、生成されたdocs/docs.go内の新しい構造体を理解できず、「そんなフィールドは知らない (unknown field)」とコンパイルエラーを吐き出してしまうのです。

swagコマンドを最新にしただけでは、プロジェクトが実際に参照するライブラリのバージョンは変わらない、というのがこの問題の核心です。

---

解決策：プロジェクトのライブラリを更新する

解決策は非常にシンプルです。プロジェクトが依存しているswagライブラリを最新バージョンに更新するだけです。

お使いのプロジェクトのルートディレクトリで、以下のコマンドを実行してください。

go get -u github.com/swaggo/swag

• go get: Goモジュールの依存関係を更新するコマンドです。
• -u (update): 指定されたパッケージを最新のマイナーバージョンまたはパッチバージョンに更新します。

このコマンドを実行することで、go.modファイル内の github.com/swaggo/swag のバージョンが更新され、swagコマンドが生成したコードと、ビルド時に参照されるライブラリのバージョンが一致します。

その後、再度 go build を実行すれば、エラーが解消されているはずです。

---

予防策とベストプラクティス

この問題を将来的に避けるために、以下の点を意識すると良いでしょう。

• 定期的な依存関係の更新: go get -u ./... などを利用して、プロジェクト全体の依存関係を定期的に見直しましょう。
• チームでのバージョン共有: go.mod と go.sum をGitなどのバージョン管理システムでしっかり共有し、チームメンバー全員が同じライブラリバージョンで開発できるようにしましょう。
• CI/CDでのバージョン指定: CI/CDパイプラインで swag init を実行している場合は、swagコマンドをインストールするステップと、go buildで使われるライブラリのバージョンが一致するように注意しましょう。

---

まとめ

Swaggoでunknown field 'LeftDelim'エラーに遭遇したら、CLIツールとライブラリのバージョン不一致を疑いましょう。swag initでドキュメントを再生成するだけでなく、go get -u github.com/swaggo/swagでプロジェクトが参照するライブラリ自体を更新することが解決への近道です。

これで、もうこのエラーで時間を溶かすことはなくなるはずです！