Gunosy Tech Blog

Gunosy Tech Blogは株式会社Gunosyのエンジニアが知見を共有する技術ブログです。

Swaggerでインタフェースの共有をしつつ社内管理画面を作る

こんにちは、新規事業開発室の @hoshitocat です。こちらはGunosy Advent Calendar 2018、24日目の記事です。なお、昨日の記事は @s-jcs さんの Fast as C, Slick as Ruby - Gunosy Tech Blogでした。

何も書くことを考えていなかったので、直近僕が業務で実装した管理画面について書きたいと思います。

はじめに

社内の管理画面はRailsを使って作られることが多いのですが、今回はReact + Redux + Goという構成で作ることにしました。社内ではVue + Goという構成のものは実績がいくつかあります。 tech.gunosy.io

今回Goのフレームワークとして、goaを利用しましたが、goaについては上記の記事でも紹介されているので割愛します。

React, Redux, TypeScript

今回はReactを使い、Stateの管理にはReduxを採用しました。また、社内で事例のあるVueではなくReactを採用したのはTypeScriptを使用する際にReactの方がTypeScriptとの相性が良いからです。

実装について

今回はサーバーをgoaを使って実装しており、フロントエンドの実装時にgoaで自動生成されたSwaggerを元にコードを自動生成するツールを利用した話を中心に書きたいと思います。

swagger.io

実際に自動生成して作成できるのはAPIの通信部分だけになりますが、それでもかなり実装コストを下げられたと思います。

swagger-codegen

Swaggerから自動生成できるツールは複数あるようですが、公式のやつを採用しました。

github.com

自動生成には以下のようなコマンドを実行するだけでできます。

swagger-codegen generate -i path/to/swagger.json -l typescript-fetch -o 生成したい場所

今回はTypeScriptのコードを生成してほしいので、 -l typescript-fetch と言語を指定しています。

あとは自動生成されたコードをインポートして、関数を実行するだけです。Swaggerさえ定義していれば、サーバーサイドと共通のインタフェースを用いることができるのです。すごく簡単です。

ただ、やはり課題もあるなと感じたので紹介したいと思います。

課題

2つほど課題というか大変だったと思うことを紹介したいと思います。

自動生成による辛さ

コードを自動生成しているので、ちょっとした変更も結構面倒です。

  1. goaのデザインを変更する
  2. goagen コマンドを実行してSwaggerのファイルを更新
  3. 新しいSwaggerのファイルを用いてクライアントのコードを自動生成
  4. 自動生成し直したコードを使ってロジックを書き直す

これだけの手順が必要になります。パラメータを一つ追加し忘れたとか、タイポしてしまったとかのときに結構面倒だなと思いました。

brew でインストールした swagger-codegentypescript-fetch に対応しなくなる

最新の mac OS で 最新の brew のバージョンでインストールした swagger-codegen のバージョンが 3.0.3 だったのですが、どうやら 3 系からサポートが外れてしまっていて、 2.4 をインストールしないといけませんでした。

github.com

まとめ

今回は管理画面をReact, Redux, TypeScript + Go(goa)を使って構築した際に、Swaggerからコードを自動生成して通信部分を実装した話を中心に書きました。多少課題はありましたが、実装コストを下げられたことの恩恵と比べると大した問題ではなかったのかと思います。ある程度実装の中身が隠蔽されても困らないようなものだったり、細かいチューニングをする必要のない管理画面などには向いているのかもしれないですね。