goa tips : swagger-ui を使って手っ取り早く API を試す

はじめに

折角 API を作ったら,簡単に試して,仕様も俯瞰的に確認したいものです. そんなわけで,今回は開発環境で使える swagger-ui の tips です.

swagger-ui は swagger ドキュメントを閲覧するためのサービスを提供してくれます. しかも API コンソールがついているので,ドキュメントを確認しながらその場で API を試すことが出来ます.

github.com

これをサービスとして立ち上げて,goa で生成した swagger ドキュメントをセットするというのもまどろっこしいので, goa で生成したサービスを立ち上げると,swagger-ui も一緒にサービスするようにしてしまおう.というのが今回の目標です.

swagger-ui を配置

swagger-ui の distフォルダをコピーしてきます. 以下の説明では,作業ディレクトリの swaggerui/dist にコピーしてきたと仮定します.

デザインに swagger-ui のサービスを追加

swagger-ui を使うにはデザインに以下を追加します.

var _ = Resource("swagger", func() {
        Origin("*", func() {
                Methods("GET") // Allow all origins to retrieve the Swagger JSON (CORS)
        })
        Files("/swagger.json", "swagger/swagger.json")
        Files("/swaggerui/*filepath", "swaggerui/dist")
})

開発環境でのサービスと割り切って,CORS 対策は何もしません. とってきた dist フォルダ以下のファイルをサービスするように指定しています.

実行

これで swagger-ui を使う準備は整ったので,goagen して, プロジェクトのトップで,下記のようにしてサービスを立ち上げます.

$ go run *.go

ブラウザで,http://localhost:8080/swaggerui/ にアクセスします.

f:id:ikawaha:20160921164612p:plain

これでお手軽に API を試すことが出来ます.

また,http://localhost:8080/swagger.json にアクセスすると,swagger.json の生データが得られます.

この方法のいけてないところ / はまりどころ

  • API の一覧の中に swagger-ui をサービスしている endpoint が表示される
    • なんかちょっともんにょりする
  • 持ってきた swagger-ui/dist を swagger フォルダ以下に配置する
    • goagen するごとに swagger フォルダが消されるので配置したはずのファイルが消されて「あれ?」っとなる

とはいえ,そんなに問題になることでもない.

どうしても本番でも使いたいときは,認証入れたり,CORS を適切に設定したりして下さい.