Go

Go Langで作成したAPIをSwagger UIで表示する

目次

タイトルにあるように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に詳しい。

大枠はこれくらい。

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

次に読むおすすめ記事

Go Langで新規登録のWebAPIを作成したので、認証周りをJWTで作成する。

Go Langで新規登録と退会のWebAPIを作成したので、やったことをまとめてみる。

Go LangでWebAPIを作成するために、GolangでエンドポイントにアクセスしDBからデータを取得する

Go LangでWebAPIを作成するために、まずはDockerでMySQLを構築する

Go LangでWebAPIを作成するために、Golangでサーバーを立ち上げる

この記事に対するコメント

お気軽にコメントを下さい

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

このブログは製作者の開発ログであり、厳密なテックブログではありません。
問題解決にいたらず、筆を置いているページもありますので、ご了承ください🙇‍♀️