はじめに
こんにちは！株式会社80&Companyの技術広報です。
弊社の開発部署では毎週火曜日の朝9:30から社内勉強会を行なっています。
今回の記事は社内のエンジニアがフロントエンド業務を担当していた際に、API周りの作業改善のため、スキーマ駆動開発の導入提案を社内勉強会で発表したものを紹介します。
スキーマ駆動開発を検討中の方は参考にしてみて下さい♪
読者の対象
- スキーマ駆動開発に興味がある方
- スキーマ駆動開発の導入を検討している方
スキーマ駆動開発とは
スキーマ駆動開発とはAPIのスキーマを最初に定義して、定義をもとにバックエンドやフロントエンドの開発を進める開発手法です。はじめにAPIのスキーマ定義をするため、フロント <-> バックエンド間におけるAPI仕様のずれを防ぐことができます。API仕様に変更を行う時も、API仕様書を変更してフロントエンド、バックエンドそれぞれの開発を行います。
※APIはREST APIを想定しています
※スキーマ: HTTPのWebAPIを示した仕様のことで、URL,メソッド,リクエスト、レスポンスに関する定義のこと
スキーマ駆動開発の相関図
スキーマ駆動開発の全体像は以下の通りです。
API仕様書、クライアント側、サーバ側があり、クライアント側のAPIクライアントはAPI仕様書をもとに自動生成することで、作業の手間を効率化することができます。サーバ側は、API仕様書をもとに実装します。サーバ側に関しては自動生成ではないため、仕様書通りの実装になっているかを確認するためテストを行います。
それではスキーマ駆動開発の一連の流れを確認しましょう。
スキーマ駆動開発の作業手順
1. API仕様を作成する
はじめにAPI仕様書をOpenAPIで書きます。
2. クライアント・サーバを実装する
従来の開発ではサーバ側が実装された後にフロント側の実装を行いますが、API仕様書(OpenAPI)を元に、クライアントとサーバの開発を同時並行することが可能です。
サーバ側はAPI仕様書を元に実装を行い、クライアント側はOpenAPIからモックサーバを用意することで実際のバックエンドサーバがない状態での開発を実現します。クライアント側のモックサーバの準備方法はいくつかありますが、今回の社内勉強会ではnpmで用意できるPrismが紹介されました。
3. テストを書く
テストを書いて機能追加があれば1→2→3と進めていきます。
今回はテストが3番目になっていますが、テスト駆動開発(TDD)で進める場合は1→3→2→3(→2→3…)の順番で行いましょう。
OpenAPI Specification(OAS)とは
先ほどまでOpenAPIという言葉が出てきましたが、OpenAPI Specification(OAS)というREST APIを記述するフォーマットがあり、YAML形式もしくはJSON形式でAPIの仕様を記述していきます。
OASに則って自力で記述式することは可能ですが、現在は各プログラミング言語やフレームワークによっては「OpenAPI Generator」と呼ばれるもツール・ライブラリが存在し、バックエンドまたはフロントエンドのどちらかの言語でプログラムベースで作成することも可能です。
OpenAPIについての余談
OpenAPIについて調べていると「Swagger」というキーワードがよく目につきます。
Swaggerは元々SMARTBEAR社が作っているサービスで、REST APIを定義する業界標準を目指した仕様でしたが競合する仕様としてAPI Blueprintなどが存在しました。
開発現場において上記の2つ仕様が混在するようになり、標準化の流れが起こりSwaggerをベースとしたOpenAPI Specification(OAS)が策定されることになりました。
歴史的な経緯からSwaggerはOpenAPIと同一に扱われることがありますが、現在はOASを便利に扱うためのツールの名称としてSwaggerが残っています。
スキーマ駆動開発のメリット・デメリット
メリット
- フロントエンドとバックエンドの実装を同時並行で進めることができる
- 納期を短く実装でき、開発の高速化が可能になる
- 工数を削減が期待できる
- 「OpenAPI Generator」の自動コード生成ツールを活用することで、実装やテストができるため工数と品質向上が期待できる
- API仕様書と実装が乖離しずらい
- 実装が仕様より先行していたり仕様書の更新漏れを防ぐ開発手法を採用している
デメリット
- 特定のAPI仕様を表現する際に、Open APIではどう書くのかを一つ一つ調べていく必要がある
- 学習コストがかかる
- 「OpenAPI Generator」を利用する場合も学習コストが必要
- 「OpenAPI Generator」によってはOpenAPIで非対応の機能を把握する必要がある
- 選定する「OpenAPI Generator」によっては痒いところに手が届かない可能性がある
- お使いのIDE側で予期しない挙動が発生する可能性がある
- 「OpenAPI Generator」のプログラムコードを記述する場合、静的解析ツールや補完機能においてバグが発生することがある
最後に
今回は、弊社社内勉強会で発表されたスキーマ駆動開発について扱いました。
今後も継続的に80&Companyでの社内勉強会の取り組みを発信していきます！
Qiita Organizationのフォローもよろしくお願いいたします！
最後まで読んでいただきありがとうございます！