蚊帳の中の日記

ゆるく生きてます

OpenAPIを使ってREST APIの実装を楽にする

最近のAPI開発はGraphQLが主流になっている感じがあって今更REST APIについてどうのこうのするのは時代遅れな気もするけれど、REST APIの開発をOpenAPIを使って進めたら思いの外いい感じだった。

(REST)API開発って難しい...

APIを実装するとき自分の場合はアプリが利用するAPIを実装する場面が殆どなので、アプリチームの人と「こういったURLにしてリクエストパラメータはこんな感じで...」、「レスポンスはこういうのが返ってくるようにしよう!」、「エラーの場合はどうしよう...」とAPIの仕様を話し合いながら実装に取り掛かることが多い。

ただこのフローで実装に取り掛かると色々とデメリットはある。

特にAPIの実装が出来上がるまでアプリチームがモックサーバーなどを用意して実装しないといけなかったり、実際APIを実装し終わったら意外と細かい部分で認識と違った実装になってしまって修正が増えたりすることが多々ある。API開発はいままでなかなか実装する機会がなかったので、実装する側と利用する側で適切に意思疎通を図って認識通りのものを作り上げるのがこんなにも大変とは思わなかった。

「最初の仕様決めが疎かになってるんじゃないの?最初をちゃんとしてればそんなこと起きねーだろ?」といった指摘が飛んできそうだけど、実際やってみると「あー、これ足りなかった」とか「やっぱここの仕様変えよう」とか、途中で色々状況が変わることも多いので最初のうちに全てを考慮し切るというのは難しいと思う。

どうするともっと良い感じに進められるだろうと思ってたら、OpenAPIを使ったスキーマファーストなAPI開発というのを知って試してみたのだけど抱えていた問題が解決できて以前よりもスムーズに開発を進められた。

OpenAPIを使って何が良くなったか?

OpenAPIが何か?とかスキーマファースト開発って何?に関してはググれば色々出てくるので割愛。

さっきも書いたけど

特にAPIの実装が出来上がるまでアプリチームがモックサーバーなどを用意して実装しないといけなかったり、実際APIを実装し終わったら意外と細かい部分で認識と違った実装になってしまって修正が増えたりすることが多々ある。

といった問題があった。

要は以下のようなことができれば色々解決出来るかと思う。

  • APIの仕様が決まったら、それをもとにクライアントサイドもサーバーサイドも並行して開発出来たら嬉しい
  • APIの仕様を改修するときに直ぐに共有して実装時に対応できたら楽

で、OpenAPI(というよりもスキーマファーストな開発手法)を使うと

  • OpenAPIで作ったスキーマをもとにサーバーサイドもクライアントサイドも並行して実装に取り書かれる。
  • APIの仕様に変更があった場合、スキーマファイルを直して共有すればOK

ということが出来る。まさにスキーマを第一に考えてそれをもとに実装をそれぞれが進めていくという流れ。スキーマをもとにして話すのでコミュニケーションコストが減るし、スキーマファイルを見れば実装で迷うことも少なくなる。

OpenAPIを導入するにあたって

OpenAPIをそもそもどうやって書くのか?については、公式のOpenAPI specificationに全て載ってるのでざっと読めば概要はつかめると思う。日本語で全体像をまとめている記事もたくさんあるので、そっちを見てから公式を見ると理解が早いかも。

swagger.io

実際書くときにswagger editorなどが紹介されているけど、この場合yamlをエディタで直接修正していくことになるので文法とかを気にしないといけず、最初の慣れないうちは文法エラーとか出たり、そもそも書くべきキーワードがわからなくて調べながら書くことになって時間がかかり面倒くさい。スキーマを書くのにはswagger editor以外にもたくさんツールがあって、無償で一番使いやすかったのでStoplightというツールで、用意されているフォームに必要な情報を記載していけば良い感じにファイルを生成してくれるので便利だった。

stoplight.io

後はこのスキーマの定義に沿った実装ができるようになると最高。ドキュメントと実装の差異が出ないようになれば、より完璧なAPI実装に近づける。committeeなどと組み合わせてテストを回してスキーマと差異があればテストを落とすような仕組みが有名らしく、自分はrailsを使った環境で実装していたのでcommittee-railsなどを使った(committee + OpenAPI + Rspecみたいな感じでググればたくさん関連記事が出てくる)。

後はAPIがたくさんあるとスキーマファイルも大きくなって管理がしづらくなるので、ファイル分割が必要になってくる。色々やり方はありそうだけど、OpenAPI Specの$refを使って管理するのが良さそう。

qiita.com


生成されたスキーマファイルは各種ツールを通してみると綺麗に整形されるので読みやすい。OpenAPIを少し学ぶコストはあるけれど、今後のREST API開発(特にチームでの開発)に有効だと思う。

最近だとOpenAPIのスキーマからGraphQLのスキーマに変換してくれるツールなどもあるらしくて、今後REST APIをGraphQLに移行するぞ!なんてときにもいいかもしれない(まだ使ったことないのでなんとも言えないけど)。時代はGraphQLだと思うので、これを機に次はGraphQLも勉強したいな。

github.com

参考資料