Laravelでサクッとはじめる型安全なAPI開発
はじめに
私はスタートアップ企業のひとりエンジニアとして日々開発業務を行っています。
dedoc/Scrambleを使用してサクッと型安全なAPI開発プロセスを導入できたのでまとめます。
なぜ型安全にしたいのか
弊サービスではざっくり以下の構成で開発しています。
- フロントエンド: React,Typescript
- バックエンド: Laravel
バックエンドはWeb APIとして動かしていて、フロントエンドでaxiosなどを使用して問い合わせる流れです。
ある程度サービスが育っていく中で、開発の課題として以下の認識がありました。
フロントエンドとバックエンドの連携
バックエンドで項目名やバリデーションルールを変更したときに、もちろんフロントエンドも修正しなければいけないのですが、忘れることもあります。
意識だけでそれをやっているのがなかなかきつくなってきたので、仕組みからカバーしたくなったのです。
車輪の再発明
APIの数が増えたことにより全体を把握することが難しくなり、既に似たようなAPIがあるにもかかわらず一から作ってしまい、後から気づいてマージする…みたいなことが何度がありました。
ドキュメントはソースコードをみよ
また「ドキュメントはソースコードをみよ」状態なのも嫌でした。一人開発なので現状困ってはいないものの、私の個人的な希望として複数人開発に移行しやすい状態にしておきたかったのです。
これらを解決するためにインターネットの海を泳いだところ、OpenAPIやらスキーマ駆動開発を知り、めちゃくちゃやりたいゾ～！となったので、やりました。
そもそもOpenAPIやスキーマ駆動開発ってなによ、という方はこの記事では説明しませんのでご了承ください。参考までに以下のリンクを張っておきます。
さあ始めよう
型安全にするからにはAPIの定義ファイルが必要なのですが、自分で一から作ると気が狂います。というか終わりません。
こういうのはすごい人がすでに開発しているはず、という気持ちで検索すると大体あります。本件も例外ではありません。Laravelのような息が長いフレームワークのいいところだと思います。
そして検索するとあるではないですか。dedoc/scrambleが。 執筆時点（2024/10/25）で1.2kスター、最終リリースが3日前なので今も活発に開発してくれているようです。ありがたすぎる。
dedoc/scrambleの導入
composer経由でインストールします。
composer require dedoc/scramble
すると以下のルートが勝手に増えています。
- /docs/api - APIドキュメントを返すルート
- /docs/api.json - API定義ファイルを返すルート
弊サービスから生成されるものをお見せすることはできないので、dedoc/scrambleがデモとして公開してくれているものを参考に張り付けます。
localhost/docs/apiに接続したときのイメージ
はい、最高ですね。
プロジェクトディレクトリ配下のroutes/api.phpを参照してドキュメントを自動的に生成するので、更新の手間がありません。
また、.envでAPP_ENV=localが定義されている場合のみこれらのルートが生成されるため、本番環境でうっかり公開…みたいなこともありません。
routes/api.php以外も参照したい場合や、生成されるURLを変更したい場合のカスタマイズも容易です。
ドキュメントも充実しているので、たいていのやりたいことはできると思います。
おわりに
dedoc/scrambleすごすぎて震えました。
実際の開発では、/docs/api.jsonで生成される定義ファイルをもとに、コミット時に自動で型チェックを行うようにしています。
今日からサクッと型安全なAPI開発を始めてみませんか。
Discussion