API スキーマ管理は大きく2つに分けられる
- スキーマファースト
- スキーマを書いてそれを元に API サーバーを実装する
- コードファースト
- サーバーを実装してそれをもとにスキーマを生成する
Helpfeel ではどうしているか？
OpenAPI でスキーマを書いているが、単にドキュメント生成のために使われている。
OpenAPI で SDK を生成することはしていない
- 生成がめんどくさいため
- 生成したコードをビルドしたうえで GitHub にコミットしたり...
- サーバーもフロントも同じ開発者が見ていることが多いのも要因としてある
- きっちり API 仕様を管理しなくても実装を把握しているため
既存ライブラリ比較
そこで開発されたライブラリ
OpenAPI に課題を感じていたため、発表者の niboshi さんが個人的に作り始め、メンバーにも「ええ感じやん」と言ってもらえたので導入された
- 「ええ感じやん」と言ってもらえるかどうかが重要
- AsIs (OpenAPI の課題) と、ToBe を整理したドキュメントを書いたりした
- ハンズオン会を開催した
ライブラリを自社開発するリスク
- メンテナンス性
- メンテする社員がいるのか？
- ググっても情報が出てこない
じゃあどうするのか？
- 小さく導入を始める
- 1行追加すれば利用可能にした
- 撤退しやすくする
- 1行消せば戻せる
- AI にサポートしてもらう
- TypeScript の型定義を書くのが大変だったが、AI は得意なのでサポートしてもらう
なんで既存の OpenAPI とかを使わなかったのか？
聞いた感想
- 私も基本 OpenAPI を型管理に使っているが、基本的にはスキーマファーストの実装となるので「実装を修正した時に API スキーマの修正を忘れがち」は結構起こる。
- この点は API スキーマのテストを導入することで解決している
- OpenAPI から生成される API Client は基本的に微妙なので、私も使っていない
- API 仕様を型で表現するというのは、TypeScript をうまく活用した解決方法でよさそう
- 導入が簡単なのも良さそう
