Swaggerを導入してみた話

バックエンド兼Androidアプリエンジニアの高橋です。

前回の更新から大分空いてしまいました。

入社してから早2ヶ月を過ぎまして、ブログに書きたいことも積もってきたものの、同時に仕事の方でもやる事が増えてきて、なかなかブログを書く時間が取れなくなってきました。

そんな状況なので今回はあまり細かい説明は抜きで、サクッと書こうと思います。

今回はSwaggerを導入した話です。

Swaggerとは？

API設計のドキュメントを生成するツールです。

(正確に言うと、ドキュメントを生成するのはSwaggerプロジェクトの一部である、Swagger UIというものです。)

ドキュメントはymlかjsonの定義ファイルに記述していくので、git管理が出来ます。

生成されたドキュメントがどんなものかは、公式にDemoページがあるので、見てもらった方が早いと思います。

petstore.swagger.io

サンプルを作ってみた

Swagger導入にあたって、サンプルプロジェクトを作ってみました。

GitHub - takkota/api-sepc-sample

起動方法や構成の概要はREADMEを見てください。

考慮した点

以下の点を考慮して作ってみました。

• 複数人で平行作業できるように、定義ファイルを分割して記述したい。
• Swagger UIの定義ファイルを使って、モックサーバーを楽に立てたい

ymlファイルの分割

Swaggerの定義ファイルは以下のように分割できます。

paths:
  /holidays:
    $ref: './paths/holidays.yml'
components:
  schemas:
    holidays:
      $ref: './components/holidays.yml'
  examples:
    holidayExample:
      $ref: './components/examples/holidays.yml'

$ref で他のymlファイルをincludeしているイメージですね。

Swaggerのymlファイルは肥大化しがちなので、基本分割して書いた方がいいと思います。

モックサーバー

モックサーバーはAPISproutというものを使って、Swaggerのymlファイルからモックサーバーを自動生成しています。

しかし、APISproutは上記のような分割したymlファイルに対応しておらず、１つのファイルにマージしないといけませんでした。

ymlファイルをマージするにはswagger-merger というものがありますが、ymlファイルを編集するたびにCLIでコマンドを叩かなければならず面倒だったので、ファイルの変更を監視して自動的にマージする仕組みを用意しました。

ファイルの監視とマージする仕組みは、こちらの記事がとても参考になりました。 blog.ryou103.com

更に、モックサーバーもファイル監視の仕組みも全部コンテナ化し、作業者は docker-compose up するだけで、仕組みをあまり意識する事なく作業できるようにしました。

Swaggerを導入して得られるメリット

まだ導入したばかりですが、以下の点がメリットに感じています。

• 設計がドキュメントとして残るので、レビューがしやすい。
• モックサーバーを建てられるので、フロントエンドの作業をブロックしない。(バックエンドの実装を待つ必要が無い)

Swaggerを運用する時の考慮ポイント

Swaggerを導入した事で、逆に気を使わなければいけない事も出てきました。

• 複数人で平行作業する場合、予め命名規則を統一しないといけない。
• Swaggerの構成について、予めチーム内で認識を合わせておかないといけない。

ここらへんは試行錯誤中ですが、READMEに書いたりesaやdocbaseなどを使って管理するのが良いのでしょうか...?

最後に

(なんだかんだ長くなってしまいました...)

Swaggerは便利ですが、当然API設計を書く作業コストだったり、メンテナンスするコストは発生します。

しかし、フロントエンドとバックエンドの担当が別れているチームにおいては、APIの仕様をやり取りする手間を大幅に削減できるので、トータルで見たら導入して損は無いと個人的には思います。

最後になりますが、LCLは新しいツールも抵抗なく導入できるチームです。

開発フロー改善のためにもっといいツールを提案していただける方を絶賛募集中です！ www.lclco.com