タイトルにあるようにSwaggerで作成したいのであれば、yamlを作成すればいい。

だけど、そんなことをするのは面倒くさい。

というのもNestJsではデコレーターを追加するだけで自動でSwagger UIを作成してくれた。

そこでGoでも同様な手順で実現できるライブラリを探してみた。

swaggo/swag

swaggo/swagを使えばできそうだったので試してみた。

インストール

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

アノテーションを作成する

main.goにアノテーションを追加する。

// @title sample api
// @version 1.0
// @description this is sample apigw

// @host localhost:18080
// @BasePath /api/v1

// @tag.name accounts
// @tag.description about accounts request
func main() {
	handlers.HandleRequests()
}

記入後にswag initを実行する。

.
├── docs.go
├── swagger.json
└── swagger.yaml

すると上記ファイルたちが生成される。

UIで確認する

これがいまいちわかなかったので、https://editor.swagger.io/に生成されたyamlファイルをコピペして見る方法にしているけど、localhost:18080/api/v1で見られるんだと思われる。

…見れないので、要調査。

⚠️ 違った。 localhost:18080/api/v1 上のURLはBaseURLだった。

まあ、問題ないので、いったん上記方法で行く。

追記：2023.12.30 Swagger ViewerVSCodeの拡張機能があった。

個別APIのアノテーションを作成する

// GetAccount
// @summary アカウントの情報を返します
// @description user_idを元にアカウント情報を返します
// @tags accounts
// @produce json
// @success 200
// @failure 401
// @router /accounts [get]
func FetchUserById(w http.ResponseWriter, r *http.Request) {
  ...

こんな感じで、アノテーションを追加すればいける。

詳細はhttps://github.com/swaggo/swag?tab=readme-ov-file#declarative-comments-formatに詳しい。

大枠はこれくらい。

後は最適化していくだけ。