Express.js初めまして、AlphaDriveでWebアプリケーションエンジニアをしている水埜と申します。ブログとして記載させていただいています。生成した型をバックエンド(Express)とフロントエンド(React)で共有API定義書の内容を自動でバリデーション&テスト何が問題だったのか?AlphaDriveでのプロダクト開発体制とエンジニアチームが組成される前段階から外部業者と共にプロダクトが開発開始された経緯もあり、現在の開発チームで内製開発体制に完全移行した段階で解消すべき技術的負債が顕在化している状態でした。バックエンドのAPI一覧がGit外のドキュメント上(Excel)で管理されており、以下のような問題点が存在しておりました。ドキュメントの内容が正確でない実装後に毎回ドキュメントをアップデートする必要があるのですが、どうしても更新が後手にまわりAPI定義書の内容がアプリケーションの実態と乖離していってしまう可能性がありました。ドキュメントの内容が間違えていたとしてもそれに気づくことができるような仕組みがないためドキュメントとしての信頼性が低い状態でした。バージョン管理が行えないGit外で管理していたため過去のAPI定義がどうなっていたのか知る術がなく、ドキュメントの管理が難しい状態でした。仕様の変更の際に差分が分かりにくい変更の差分がわかりづらく、Githubのプルリクのように変更をレビューする仕組みもありませんでした。各API間で共通となるパラメーターの管理がしにくい共通となるパラメーターを共通化する仕組みがないため、ドキュメント内で同じことを複数箇所で何度も書くことになります。変更が生じた場合複数箇所の記述を全てを書き直す必要があり、変更漏れが生じる可能性がありました。フォーマットが自由記述になってしまい統一されない定義書のフォーマットも決められておらず、更新した定義書をレビューする仕組みもなかったためフォーマットが統一されていませんでした。コードやテストの自動化がしづらいフォーマットが統一されていないため、定義書から型定義を自動生成したりバリデーションテストを自動実行する仕組みが導入しづらい状況でした。どのように改善していったか?今後開発を進めていくにあたって、OpenAPIを導入しスキーマ駆動で開発を進めていくように変更しました。APIを記述するためのフォーマットのことです。以下公式からの引用です。APIの標準的で言語に依存しないインターフェースを定義しており、人間とコンピューターの両方が、ソースコードやドキュメントにアクセスしたり、ネットワークトラフィックの検査を通じて、サービスの能力を発見し理解できるようにするものである。適切に定義されていれば、コンシューマーは最小限の実装ロジックでリモートサービスを理解し、対話することができる。OpenAPIの定義は、APIを表示するためのドキュメント生成ツール、様々なプログラミング言語でサーバーやクライアントを生成するコード生成ツール、テストツール、その他多くのユースケースで利用することができる。言語に依存しない人間とコンピューターの両方が理解できる定義をもとにコードやテストを生成できるなどの特徴があります。これを使うことで以下のようなメリットがあります。Gitで定義書を管理できるため、バージョン管理、レビューが可能になる。pakcageを利用することで、OpenAPIの定義書からTypeScriptの型定義を自動生成することができます。バックエンド(Express)とフロントエンド(React)両方でTypeScriptで開発しているため、リクエスト、レスポンス、DTOの型を一箇所にまとめてしまいたいと考えています。現在はポリレポでの運用をしておりバックエンドのみで自動生成した型を利用しておりますが、いつかはモノレポにして型定義をバックエンド、フロントエンドで共通化してしく予定です。パラメータのバリデーションを導入(予定)API定義書を生成しても、定義通りにAPIを叩いてもらえるとは限らず、パラメータをバリデーションする必要があります。バリデーションを手作業で実装すると定義と乖離してしまう可能性があるため、OpenAPIの定義からバリデーションを生成したいと考えています。express-openapi-validatorというライブラリを使用すれば自動バリデーションが実現できそうであり、検討していきたいです。実際のレスポンスが定義通りかチェックするテストを自動生成(予定)ドキュメントと実装の乖離を防ぎ、よりスキーマを堅牢なものとするためにはレスポンスが定義通りのものかチェックするテストが必要です。こちらもまだ構想の段階ですが、openapi-response-validatorというライブラリが目的に合致している気がするため、導入を検討していきます。まとめ以上がAlphaDriveでスキーマ駆動開発を実現しようとしているお話でした。OpenAPIを導入したばかりのため恩恵を受けている気はしませんが、一度環境を整備してしまえばだいぶ開発者体験が向上される気がしています。最終的には以下の開発フローを目指しています。OpenAPIでのAPI定義を書き、プルリクエストをオープンAPI定義をレビューし、問題なければマージAPI定義から型定義を生成し、バックエンド&フロントエンドの実装に着手レスポンスが定義通りであることを保証するユニットテストをopenapi-response-validatorで作成パラメーターをexpress-openapi-validatorでバリデーションバックエンドとフロントエンドのプルリクエストをオープン&レビューもし上記の開発フローが実現されれば、ドキュメント更新や型定義の時間を削減でき、生産性を大幅に向上できるのではないかと目論んでいます。reserved.引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。