🫣

GoでSwaggerを使ってみた

2025/01/31に公開

詰まったのでAIに助けてもらいつつ

以前GoでSwaggerを使おうとしたのですがうまいこと構築ができませんでした?
どうやらライブラリを追加するだけではダメみたい?

Macだと.zshrcに設定が必要だった。

設定が思ったようにいかずCursorを使用して構築しました。詰まったところあるがいい感じで使えた。

サンプル参考に試してみてください

git cloneして動かしてみてください。
これが完成品

Shopping API with Swagger

GoとSwaggerを使用したシンプルなショッピングカートAPIのサンプルアプリケーションです。

環境要件

  • Go 1.16以上
  • Make

Macでの環境構築手順

1. Goのインストール(未インストールの場合)

# Homebrewを使用してGoをインストール
brew install go

2. 環境変数の設定

以下の内容を~/.zshrcに追加してください:

# GOPATHの設定
export GOPATH=$(go env GOPATH)
export PATH=$PATH:$GOPATH/bin

設定を反映:

source ~/.zshrc

3. プロジェクトのセットアップ

# プロジェクトディレクトリの作成と移動
mkdir three_layerapp
cd three_layerapp

# Goモジュールの初期化
go mod init main

# 必要なパッケージのインストール
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files
go get -u github.com/gin-gonic/gin
go get -u github.com/gin-contrib/cors
go get -u github.com/google/uuid

# Swaggerのインストール
go install github.com/swaggo/swag/cmd/swag@latest

4. Makefileを使用した開発

# 初回セットアップ(依存関係のインストール、Swaggerの生成、ビルド)
make setup

# アプリケーションの実行(Swagger生成含む)
make

# その他の利用可能なコマンド
make run          # アプリケーションの実行
make swagger      # Swaggerドキュメントの生成
make build        # バイナリのビルド
make test         # テストの実行
make clean        # クリーンアップ

APIエンドポイント

  • GET /api/v1/items - 全ての商品を取得
  • POST /api/v1/items - 新しい商品を追加

Swagger UI

アプリケーション起動後、以下のURLでSwagger UIにアクセスできます:

APIの使用例

商品の追加(POST)

curl -X POST http://localhost:8080/api/v1/items \
  -H "Content-Type: application/json" \
  -d '{"name": "テスト商品", "price": 1000}'

商品一覧の取得(GET)

curl http://localhost:8080/api/v1/items

プロジェクト構造

three_layerapp/
├── main.go           # メインアプリケーション
├── handlers/         # APIハンドラー
│   └── shopping.go
├── models/           # データモデル
│   └── shopping.go
├── docs/            # Swaggerドキュメント(自動生成)
├── Makefile         # ビルドと開発用コマンド
└── README.md        # プロジェクトドキュメント

注意事項

  • このアプリケーションはメモリ上にデータを保存するため、サーバーを再起動するとデータは消去されます。
  • CORSは全てのオリジンからのアクセスを許可する設定になっています。

Discussion