i Cubed Systems Engineering blog

株式会社アイキューブドシステムズの製品開発メンバーが、日頃のCLOMO開発の様子などを紹介します。

OpenAPIの導入

はじめに

アイキューブドシステムズでCLOMOのサーバーサイドを担当している Kakuno です。 今回は弊社のOpneAPIの導入の取り組みについて紹介したいと思います。

CLOMOのAPI仕様書はどうなっていたか

履歴を辿ると、最初にAPI仕様書が作られたのは今から何年も前でした。 そのため、CLOMOのAPI仕様書はエクセルで管理されていて以下のような問題を抱えていました。

  • フォーマットがバラバラである
  • 更新漏れがある

エクセルのAPI仕様書だと、決まったフォーマットがあるわけではないので記載方法がバラバラになり 読みにくいのに加えて、仕様変更があった際に更新漏れなども発生する可能性があります。 APIを使う側のモバイル開発チームからも、これらを改善したほうが良いという声もいただいたので 今回OpenAPIにリプレイスしようという改善を行いました。

そもそもOpenAPIとは

もともとはSwaggerと呼ばれていたもので、それを拡張したものがOpenAPIになります。 What Is OpenAPI? SwaggerではREST APIの仕様書が書けます。 公式のSwagger Editorを使うことでどんな事ができるのかイメージがつかめると思います。

OpenAPIと連携してさらに出来ること

OpenAPI形式で仕様書を書くことにより、他のツールと連携することで様々な恩恵を受けることが出来ます。

■モックサーバーの構築 Prizmを用いればモックサーバーの構築も簡単にできます。 これを導入すると、OpenAPI仕様書が完成すれば実装をまたずしてモックのレスポンスを返すことができます。これにより、スキーマファーストの開発が出来るようになります。サーバー側の実装をまたずしてアプリケーションの実装に入れます。

■仕様書とレスポンスの差異の検知 committeeを使うことによって、OpenAPI仕様書とレスポンスが一致しているか検証できます。 RSpecに組み込む形で導入でき、一致していない場合RSpecが失敗するようになります。

どのように改修をしたのか

まず一旦、エクセルのAPIを見ながらOpenAPIに変換していく作業を行いました。 Stopligth Studio というツールを用いてOpenAPIの実装を行いました。 前述したSwagger Editorではymlを直接編集していくのですが、こちらのツールはUIで直感的にAPI仕様書の記載ができます。

全て変換すると膨大な数になり、手戻りが発生した場合に大変な事になるので、お手本となるプルリクエストを作成し、一旦チーム内レビューを行い、お手本となるものをFIXさせました。あとはAPIの数の分だけ実装を進めていき完成させてます。 また、レビューの際にはGitHub上で簡単に見られるように、ChromeのExtentionのswagger-viewerを使用して確認をしてもらいました。

小さな改善をコツコツと

今回のOpenAPIの導入により、表向きにはあまり見えない改善であるが大きな進歩があったと思っています。特にcommiteeの導入のおかげで、実際既に何個かAPI仕様書と実装がずれているのが発覚しました。 今後は変更があれば検知できるようになったのも大きな恩恵です。

静的解析ツールの導入で紹介したように、こういった小さな改善をコツコツと進めています。 開発を進めていく上で、目に見える改善に注目がいきがちですが、こういった縁の下の力持ちというような改善を進めていくのも大事だと感じています。