このエントリーをはてなブックマークに追加

はじめに

golangとechoを使ってJSON APIのswaggerを生成する方法について書きます。
swag というツールが提供されているので、基本的にはこのツールを使っていきます。

今回作ったサンプル置き場

使い方だけ見たい方はgithubのコードを見るのがいいと思います。

https://github.com/ken-aio/go-echo-sample/tree/v2

流れ

swagを使ったswaggerドキュメントの生成は↓の流れで行います。

  1. コメントを書く
  2. 自動生成する
  3. swagger uiのhandlerを設定する
  4. swaggerを開く

実際にサンプルプロジェクトを使ってswaggerを作ってみます。

1. コメントを書く

API全体の設定

まずは全体の設定を main の中に書いていきます。
中身は利用に関する規約のURL、ライセンス情報、認証用のhttp header情報などの設定が出来ます。
今回は内部で使うだけの場合を想定して、最低限の設定だけをしてみます。
※ 詳細の設定内容はこちら

1
2
3
4
5
6
7
8
9

// @title Swagger Example API
// @version 1.0
// @description This is a sample swagger server.
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:1313
// @BasePath /api/v1
func main() {
...

各エンドポイントの設定

グループに所属しているユーザの一覧を取得するAPIのswagger docを設定します。
group_idをpathパラメータに受け取って、性別（gender）をqueryパラメータで受け取ります。
※ 詳細の設定パラメータはこちら

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// getUsers is getting users.
// @Summary get users
// @Description get users in a group
// @Accept  json
// @Produce  json
// @Param group_id path int true "Group ID"
// @Param gender query string false "Gender" Enum(man, woman)
// @Success 200 {array} main.User
// @Failure 500 {object} main.HTTPError
// @Router /groups/{group_id}/users [get]
func getUsers(c echo.Context) error {

2. 自動生成する

設定した内容に従ってswagger uiのもととなるyamlを自動生成します。
まずはswagのコマンドをインストールします。

1

$ go get -u github.com/swaggo/swag/cmd/swag

自動生成します。
生成すると、docsというdirが出来て、この中にswaggerのjsonとyamlが生成されます。

1

$ swag i

3. swagger uiのhandlerを設定する

次にechoからswagger uiを呼び出せるようにhandlerの設定を行います。
echo-swagger というライブラリがあるので、こちらを使ってechoからswagger uiを呼び出せるようにします。
routerを初期化するタイミングでswagger uiの設定をします。

1
2

	// swagger
	e.GET("/swagger/*", echoSwagger.WrapHandler)

また、docsをimportする必要があるので、以下のようにmainにdocsをimportしておきます。

1
2
3

import (
	_ "github.com/ken-aio/go-echo-sample/docs"
)

4. swaggerを開く

ここまで出来たらあとはサーバを立ち上げてswagger uiにアクセスするだけです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ go run main.go

   ____    __
  / __/___/ /  ___
 / _// __/ _ \/ _ \
/___/\__/_//_/\___/ v4.0.0
High performance, minimalist Go web framework
https://echo.labstack.com
____________________________________O/_______
                                    O\
⇨ http server started on [::]:1314

この状態でブラウザで以下のURLにアクセスすると、swagger uiが表示されると思います。

http://localhost:1314/swagger/index.html

Try it outから実際にAPIを叩いてみると、APIがたたけることを確認できます。

echo v4対応

現時点ではecho v4が出たばかりということもあって、echo-swaggerがv4では使えませんでした。
echo-swaggerをforkして、echoのバージョンをv4にあげたものが以下のリポジトリにあるので、これを使えばecho v4の環境でもecho-swaggerを使うことが出来ます。

https://github.com/ken-aio/echo-swagger

まとめ

go docを書くだけでswaggerが出来てしまう超便利なswagをechoで使う方法でした。
APIドキュメントを書くのが面倒な人にはおすすめです。