こんにちは、Progateの関川です。
ユーザーの学習体験をよくするLearningExperienceチームに所属しており、主にサーバーサイドの開発をしております。
＊本記事はProgate Advent Calendar 14日目の記事になります。
はじめに
弊社では昨年度から学習体験の向上できるよう、演習画面のSPA化を行うプロジェクトが進行中です。（各プログラミング言語によってフロントエンドの構成が変わるため、言語ごとに絶賛移行中でございます）。今回は、そのプロジェクトで新しいフロントエンド向けに作るAPIの開発で行っているスキーマ駆動開発について紹介したいと思います。 （Progateの開発ではバックエンドはRuby on Rails、SPA化されたフロントエンドはReact + TypeScriptを用いております）
スキーマ駆動開発
スキーマ駆動開発とは、APIのスキーマを最初に定義し、その定義をもとにAPIを実装するバックエンド、APIを利用するフロントエンドの開発を進める開発手法のことです。
導入背景
今回のプロジェクトが始まった当初は、新しいAPIを作るにあたり、今までなかったAPIドキュメントを一緒に作成することにしましたが、この時はまだスキーマ駆動開発をしていない状態でした。
演習画面のSPA化ではバックエンド側の実装は基本的にもともと動いているAPIをリプレイスするものになることが多かったので、バックエンド側の実装と同じタイミングでAPIドキュメントの更新をしていました。しかし実装のレビューをしてもらう段階で、フロントエンド側で必要なデータがなかったり、レスポンスで受け取るデータの型が異なるといったことが発生し、その修正をするということがよくありました。
バックエンド側とフロントエンド側でコミュニケーションをとっていたつもりでしたが詳細な仕様を決め切れていませんでした。
そこで最初にスキーマをきちんと決めてバックエンド側とフロントエンド側で認識を合わせることで、APIの実装の手戻りを減らしたかったという背景がありスキーマ駆動開発を導入しています。
スキーマ駆動開発で使用しているもの
以下に、導入したフォーマットやツール、ライブラリを紹介します。
スキーマの定義
スキーマのフォーマットはOpenAPI Specification(以降OpenAPIと呼びます)を使用しております。OpenAPIをYAML形式で記述しております。
YAMLファイルを修正する際は、Stoplight StudioというOpenAPIをGUI上で編集することができるものを利用しています。
ドキュメントの閲覧
上記に記述したStoplight Studioを利用しています。編集と閲覧をStoplight Studioで行うことができます。また、github 上でも閲覧できるようにGoogle Chromeの拡張機能でswagger-viewerを使うこともあります。
開発
バックエンドでのテストではcommittee、committee-railsというgemと定義したスキーマを利用して、APIのリクエストやレスポンスの検証を行うことが出来ます。
フロントエンドでは、OpenAPI generatorを用いて定義したスキーマからAPIクライアントや型の自動生成しております。
導入後の変化
目的であったAPIの実装の手戻りを減らすことは達成できました。またドキュメントをもとにテストをするので、実装とドキュメントが必ず一致するのでメンテナンスされないということが発生しないのも良いなと思いました。
まとめ
今回のプロジェクトの当初はスキーマ駆動開発という言葉すら知りませんでした。修正の手戻りがよく発生していたときに、先輩方にスキーマ駆動開発について教えていただきました。普段、自分はプログラミング言語などについての技術を勉強しがちですが、開発手法についてもちゃんとアンテナを張ろうと思ういいきっかけになりました。
明日はdevildogs さんによる Progate AdvendCalendar 15日目です。お楽しみに！
