「Scramble」を使ってみた

Laravel向け OpenAPIドキュメントジェネレーター 「Scramble」を使ってみた 2025/02/08 札幌PHP勉強会 Kou

自己紹介 🦌 Kou (@kou_tech_1017) 💻 プログラマー PHP、React、Azure Sapporo Engineer Base運営

今日話すこと 主に「OpenAPI」について話します

「OpenAPI」はご存知ですか？

「OpenAPI」とは、 RESTful APIの設計とドキュメント化 のための標準仕様

OpenAPIの利点 Gitなどのバージョン管理ツールと親和性があり、変更 履歴や差分管理が容易である 常に最新の仕様を全員で共有できる スキーマに基づいて効率的な分業開発が可能となる

OpenAPIの不利点 学習コストが必要となる OpenAPIのスキーマの範囲外での柔軟な操作や部分的 なレスポンス制御が複雑になる 仕様書の管理には専用ツールやエコシステムが必須と なることが多い Apidog、Stoplight

負のスパイラル 1. 設計書の手動管理はメンテナンスが大変 2. 情報の更新が追いつかず、古くなる 3. 仕様書がコードと乖離し、開発に影響を 与える

Laravelのコードから 自動生成できないかな...

今回紹介するのが...

Scramble

Scrambleとは Laravel用のOpenAPIドキュメントを自動生成 するツール コードから直接APIドキュメントを生成できる Stoplight ElementsでUI表示ができる https://scramble.dedoc.co/

• https://scramble.dedoc.co/

Scrambleの主な特徴 静的コード解析とLaravelの規約を活用して、APIドキ ュメントを自動生成 リクエスト・レスポンス・エラーをすべて自動でドキ ュメント化 アノテーションは必須ではなく、必要なときだけ追加

他のライブラリとの比較 例 ) ユーザー一覧を取得するAPI

l5-swagger PHPDocアノテーションを使用して、APIドキュメントを記 述する アノテーションが冗長で、メンテナンスが大変 フィールドの追加・変更時にアノテーションの修正が必要 コードのノイズが増える

Laravel-OpenAPI Laravel-OpenAPIでは、アトリビュート（Attributes） を使ってAPI仕様を記述する 設定が煩雑 仕様変更時にコードの修正が必要になる ドキュメントのためのコードが増え、可読性が下がる

Scrambleだと...

これだけ！！

Scrambleだと コードベースから仕様書を自動生成する 記述量が圧倒的に少ない メンテナンスも容易

デモ

所感 実際に活用する場合、Scrambleは型推論を活用して自動生 成してくれるものの、完全にアノテーション不要というわ けではなく、一部手動記述をする運用になりそう。 例）APIの詳細な説明、具体的な値、セキュリティスキームの追加など

注意 本来の開発プロセスでは、詳細な設計書を作成 して実装に移行するのが一般的 コードファーストとした設計書はそれで別の課 題が残る

まとめ ScrambleはLaravelでのOpenAPI仕様書管理を圧倒的に効 率化するツールである。 仕様書管理に悩んだり、分業開発の現場において、 ドキュメントの自動生成を導入する利点は大きい。

ご清聴ありがとうございました