初めまして！XMileのエンジニアの白石です。
XMileでは運送業向けSaaSのロジポケの開発を担当しています。
今回は、最近ロジポケチームでOpenAPIを導入したので、その背景や導入効果についてまとめたいと思います。
OpenAPIとは
厳密には「OpenAPI Specification」の略になります。OpenAPIとは、APIの仕様を定義するためのフォーマットです。具体的には、どのエンドポイントにどのメソッドでアクセスするとどんなレスポンスが返ってくるのかのようなことをJSONやYAML形式で定義します。プログラミング言語の種類に関わらず共通の文法で定義することができます。また関連ツールと連携することで、クライアントコードを自動生成したり、GUIからAPI仕様を確認できたりと開発作業の効率化に繋がります。
導入の背景
OpenAPIは主に以下の2つを理由から導入しました。
- API仕様をドキュメントとして残すため
これまで少人数でスピード重視で開発を進めてきたため、実装に関してドキュメントを残す文化があまりありませんでした。特に既存の実装に関してドキュメントが残っていないことは大きな課題になっており、新規参入したメンバーが既存実装を理解するのに工数がかかる、API仕様が明文化されていないためフロントエンドのエンジニア向けにタスクを依頼しづらい等の問題が定期的に起きていました。 - エンジニア組織をフロントエンドとバックエンドで分業するため
プロダクトリリースしてしばらくは、少数のエンジニアがフルスタックにフロントエンド〜バックエンドまで一気通貫で実装していました。しかし実際には各々フロントの方が得意、バックエンドの方が得意のようにどちらかに強みを持つ場合が多く、またエンジニア組織が拡大するにつれてフロント専門、バック専門のプロフェッショナルの方も増えてきました。そこでOpenAPIを取り入れてフロント・バックを分業したスキーマ駆動な開発を可能にすることで、各々が得意な分野の開発に集中できる状態を目指しました。
どのように導入したか
OpenAPI導入後の開発は以下のような流れで進めております。
- バックエンドエンジニアがOpenAPIを定義するプルリクを作成
- フロントエンドの実装担当者から定義について承認をもらう。(他のエンジニアもレビューします)
- 合意した定義を元にフロント、バックのそれぞれの開発を着手する
一言にOpenAPIの導入と言っても、様々なツールや関連するライブラリが存在します。現段階で我々のチームでは以下のツールやライブラリを導入しています。
- Redoc(Viewer)
API定義のViewerとしてRedocを導入しています。他のViewerを使ったことがないですが、現状Redocで特に不満は感じていません。とてもシンプルなUIであり、既存のAPIの仕様をストレスなく確認することができます。
- committee(API定義のテスト)
OpenAPIを導入しても、定義がメンテされていなくて実装と差分がある・・・みたいな状態になってしまうと意味がないですよね。これを防ぐために、OpenAPI定義とAPIの実装内容が一致していることを確かめるテストとしてcommiteeを導入しています。バックエンドはRailsを使っているため、committee-railsというgemを使っています。これによりrspecでAPI定義と実装が一致していることをテストすることができます。
- orval(クライアントコードの自動生成)
orvalはOpenAPIの定義を元にクライアントコードを自動で生成してくれるツールです。具体的には、定義したAPIをReactのコンポーネントから直接呼び出せるHooksやtypescriptを使っている場合はリクエストパラメータやレスポンスデータの型定義まで生成してくれます。
導入の効果
私含めOpenAPI自体書き慣れていないメンバーもいましたが、意外と定着は早かったです。
導入の効果としては主に以下を実感しています。
- 開発生産性の向上
やはりバックエンドのタスクはバックエンドが得意な方が担当した方が早いなと感じます。(フロントも然り)OpenAPIの導入により、スキーマを定義する工数が追加で必要になりましたが、それを考慮してもチーム全体での開発生産性は導入前よりも上がっている気がします。
また同じ人がフロント、バック一気通貫で開発していた際は、バックエンドを終わらせないとフロントに着手できないというような状態でしたが、OpenAPIでスキーマを先に定義してしまえば、後はフロント、バックを並行して開発を進めていくことができるため、そういう意味でも効率的に開発できるようになりました。 - ドキュメントとして有用
API仕様について、新規参画者やフロントエンドメンバー向けに説明するコストがほとんどなくなった気がします。exampleフィールドを使ってどんな値が返ってくるかも具体的に示しているため、レスポンスのイメージもつきやすくなったかと思います。また補足説明が必要そうな項目にはdescriptionを使って補足するようにしています。 - フロントエンドの開発が効率化された、より型安全になった
OpenAPI定義を厳密に定義すればするほど、orvalで受ける恩恵も大きくなります。例えばnullableな項目をきちんと定義しておけば、orvalで型定義を生成する際にそれらの項目はオプショナルプロパティとして定義されます。またenumの定義も同様に型定義に反映されます。
今後の展望
最後に今後の展望をまとめます。
- 文法チェックの自動化
導入当初は、誤った文法で定義されたOpenAPIのPRがそのままapproveされ、デフォルトブランチにマージされてしまい、それが原因でorvalによるクライアントコードの自動生成が上手くいかないことがよくありました。今後はpre-commitやCIでOpenAPIの文法チェックを組み込むことで、文法ミスを事前に検知できるようにしていきます。 - 文法を学ぶ
これは個人的な目標ですが、OpenAPIの細かな文法についても学んでいきたいと思います。OpenAPIは最低限の定義だけであれば簡単に書けてしまいますが、前述の通りより厳密に定義していくことでorvalやcommiteeで受けられる恩恵も大きくなってきます。また厳密に定義することでドキュメントとしても有用なものになってくるかと思います。 - 関連ツールを使いこなして開発を少しでも楽にする
わざわざ工数をかけて定義するOpenAPIです。導入済みのツール以外にも定義したOpenAPIを活用することで、開発を楽にしてくれるものがあると思っています。そうしたツールも今後導入を検討していきたいと思います。
最後に
私たちは、ノンデスクワーカー版のエス・エム・エスさんやメドレーさん、エムスリーさんのような大きな存在になることを目指しており、エンジニアとして多角的な視点から社会課題に取り組みたい方を歓迎します!
人口減少が進むなか、日本の最重要課題に取り組める事業を推進したい方は、共に働きましょう。
Discussion