Table of Contents
タイトルにあるように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 requestfunc 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に詳しい。
大枠はこれくらい。
後は最適化していくだけ。
