GoプロジェクトのAPIドキュメントを自動生成する方法

プログラミング

2020.12.24

今回は仕事にてswaggo, redoc-cli を使用したAPIドキュメントの自動生成を経験したので、

備忘録がてらそのノウハウを紹介したいと思います。

サンプルプログラムは GitHub に配置したのでそれをもとに進めていきます。

必要な方はCloneして使ってみてください！

ドキュメントの自動生成は swagger がよく使われており、今回swaggerファイルの生成には swaggo を、ドキュメントの生成には redoc-cli を使用します。

コマンド数発で綺麗なドキュメントを生成してくれる優れものなので、おすすめですよ〜！

動作環境
swag をダウンロードする
アノテーションを付ける
swagger.yamlを生成する
APIドキュメントを出力
最後に

動作環境

以下の環境を前提に記述していきます。

go: 1.15.5 linux/amd64
swag: 1.7.0

swag をダウンロードする

サンプルプログラムをもとに解説します。

コンテナに入って作業します。

$ docker exec -it sample-api-server ash

swagをダウンロードします。

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

確認

$ swag -v
swag version v1.7.0

アノテーションを付ける

最終的なドキュメントの生成のため、アノテーションをつけていきます。

こちらやこちらを参考にアノテーションを付けていきました。

今回は以下の様にAPIの関数にアノテーションを付けてみました。（あくまでサンプルです）

package main

import (
	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
	"net/http"
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server.
// @contact.name Example API Support
// @contact.url http://example.com/support
// @contact.email support@example.com
// @BasePath /
func main() {
	e := echo.New()

	e.Use(middleware.Logger())
	e.Use(middleware.Recover())

	//routing
	e.GET("/hello-world", helloWorld())

	//exec server
	e.Start(":8000")
}

// @Summary hello world
// @Description say hello world
// @ID hello-world
// @Accept  json
// @Produce  json
// @Success 200 {string} string "OK"
// @Router /hello-world [get]
func helloWorld() echo.HandlerFunc {
	return func(c echo.Context) error {
		return c.String(http.StatusOK, "Hello, World")
	}
}

swagger.yamlを生成する

アノテーションが書けたので次はswagger.yamlを生成します。

main.goがあるディレクトリで以下のコマンドを打ちます。

$ swag init

以下の様に表示されていれば成功です。

2020/12/22 13:26:13 Generate swagger docs....
2020/12/22 13:26:13 Generate general API Info, search dir:./
2020/12/22 13:26:18 create docs.go at docs/docs.go
2020/12/22 13:26:18 create swagger.json at docs/swagger.json
2020/12/22 13:26:18 create swagger.yaml at docs/swagger.yaml

/docsディレクトリが新たに作成され、その中に以下のファイルが生成されました。

docs.go
swagger.json
swagger.yaml

APIドキュメントを出力

さて、いよいよドキュメント生成です。

様々な方法があるのですが、今回はredoc-cliを使用してHTMLファイルで出力する方法を選択しました。

redoc-cliのインストール

$ npm install -g redoc-cli

以下のコマンドでドキュメントを生成することができます。

$ redoc-cli bundle <swagger.yamlへのpath> -o <出力ファイル名>

実行

$ redoc-cli bundle swagger.yaml -o ./document.html
[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0
Prerendering docs

🎉 bundled successfully in: ./document.html (953 KiB) [⏱ 0.322s]

生成されたHTMLファイルをブラウザで開くととても見やすいHTMLドキュメントが生成されています！すごい！