Go の HTTP サーバーで Swagger UI を提供する

Go の HTTP サーバーで Swagger UI を提供する際、アセットを用意して自前で FileServer を立てても良いですが、 go-openapi/runtime のミドルウェアを使うと便利です。

+import "github.com/go-openapi/runtime/middleware"

+	handler = middleware.SwaggerUI(middleware.SwaggerUIOpts{}, handler)
 	log.Fatal(http.ListenAndServe(":8080", handler))

このようにハンドラーに適用するだけで /docs で Swagger UI を提供することができます。

このミドルウェアは html/template で生成した自前の HTML を返すのですが、その HTML は UNPKG のアセットを参照する形になっています。デフォルトは最新バージョンを参照するようになっているので更新作業なども不要です。

ミドルウェアにはオプションが用意されているので、アセットのバージョンを固定したり HTML のパスを /docs から変更することもできます。

// SwaggerUIOpts configures the Swaggerui middlewares
type SwaggerUIOpts struct {
	// BasePath for the UI path, defaults to: /
	BasePath string
	// Path combines with BasePath for the full UI path, defaults to: docs
	Path string
	// SpecURL the url to find the spec for
	SpecURL string
	// OAuthCallbackURL the url called after OAuth2 login
	OAuthCallbackURL string

	// The three components needed to embed swagger-ui
	SwaggerURL       string
	SwaggerPresetURL string
	SwaggerStylesURL string

	Favicon32 string
	Favicon16 string

	// Title for the documentation site, default to: API documentation
	Title string
}

このパッケージには RapiDoc と Redoc のミドルウェアも含まれており、前述の Swagger UI と同じように使えます。

	handler = middleware.RapiDoc(middleware.RapiDocOpts{}, handler)

	handler = middleware.Redoc(middleware.RedocOpts{}, handler)

便利ですね。