Go Swaggerのコメント地獄から抜け出す - Swaggoを作りました

こんにちは。

GoでAPI開発をしていて、Swaggerコメントのせいでストレスを感じたことはありませんか？

私は毎回こんな感じで苦労していました。

• "// @Param の4番目の引数って required だっけ、description だっけ..."
• "dto.UserRequest のタイプミスに、実行時になって初めて気づく"
• "このコメントが何を意味するのか毎回検索する"

そこで、Swaggo という VS Code 拡張を作りました。

どう動くのか？

従来の方式:

// @Param id query string true "사용자 ID"  
// @Success 200 {object} dto.UserResponse "성공"  

順番を覚える必要があり、何が何なのか一目で分かりません。

Swaggo方式:

@Param(name="id", in="query", type=string, required=true, desc="사용자 ID")  
@Success(code=200, schema=dto.UserResponse, desc="성공")  

入力した瞬間に、自動で標準の Swagger コメントへ変換されます。
エディタ上では読みやすいアノテーション形式で表示され、実際のファイルには標準コメントとして保存されます。

主な機能

✅ 明示的なパラメータ名 - 順番を覚える必要なし
✅ IDE自動補完 - アノテーション名、キー、型まで自動補完
✅ 型推論 - Go構造体を自動認識
✅ リアルタイム変換 - 入力と同時に Swagger コメントへ変換
✅ ホバープレビュー - 変換結果をその場で確認
✅ スニペット - GET/POST テンプレートを提供

実際の使用例

@Summary("교실 생성")  
@Description("새로운 교실을 생성합니다")  
@Tags("classroom", "admin")  
@Accept("json")  
@Produce("json")  
@Param(name="body", in="body", type=dto.CreateClassroomRequest, required=true, desc="교실 생성 요청")  
@Success(code=200, schema=dto.ClassroomResponse, desc="교실 생성 성공")  
@Failure(code=400, schema=echo.HTTPError, desc="잘못된 요청")  
@Router("/classrooms", "post")  

なぜ作ったのか？

チームでGoによるバックエンド開発をしている中で、Swaggerドキュメントの保守があまりにもつらかったからです。

フィードバック歓迎です！

GoでAPI開発をしている方々に、本当に役立つのか気になっています。
ぜひ使ってみて、不便な点や改善アイデアがあれば教えてください！

GitHub: https://github.com/NARUBROWN/swaggo.git