はじめに
以前関わったWeb API開発の現場で、API仕様の共有に課題を感じる場面がありました。
API仕様を関係者へ共有する際、ソースコードや実装内容を確認しながら説明する必要があり、仕様確認や変更連携に手間がかかりやすい状況でした。
課題は以下です。
- API設計書が整備されていない
- API仕様を共有するたびにソースや実装者への確認が必要になる
- 仕様書と実装に差分が出やすい
- API変更を関係者へ伝えるコストが高い
この状況を改善するために、LaravelでAPIドキュメントを自動生成できるツールを調査し、資料にまとめて改善案として提案しました。
ただ、結果としてこの提案は実現には至りませんでした。
本記事では、調査したツール、比較内容、提案してみて分かったこと、そして次に同じような改善提案をするならどう進めるかをまとめます。
調査したツール
Laravel向けのAPIドキュメント生成ツールとして、主に以下を調査しました。
- Scribe
- Scramble
Scribe
Scribeは、LaravelのコードベースからAPIドキュメントを生成するツールです。
導入例は以下です。
composer require knuckleswtf/scribe
php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate
HTMLのAPIドキュメント、ブラウザ上のAPIテスター、Postman Collection、OpenAPI specの生成に対応しています。
関係者へ見せるドキュメントとしては、Scribeの方が分かりやすそうでした。
一方で、きれいに出力するにはPHPDocや設定の整備が必要です。
既存コードにそのまま導入すれば十分なドキュメントが出るというより、ある程度ドキュメント生成を意識したコード整備が必要だと感じました。
Scramble
Scrambleは、Laravel向けのOpenAPIドキュメント生成ツールです。
導入例は以下です。
composer require dedoc/scramble
インストールすると、標準で以下のルートが追加されます。
/docs/api/docs/api.json
Scrambleは、コードからOpenAPIドキュメントを自動生成しやすい点が良さそうでした。
一方で、FormRequestやAPI Resource、型定義が整理されていないと、期待した粒度のドキュメントにならない可能性があります。
OpenAPI JSONを中心に外部ツールやCI/CDとつなげたい場合は、Scrambleも候補になると思います。
比較
| 観点 | Scribe | Scramble |
|---|---|---|
| 方向性 | 人が読みやすいAPIドキュメント | OpenAPI生成 |
| 強み | 表示が分かりやすい | コードから自動生成しやすい |
| 向いている場面 | 関係者向けにAPI仕様を共有したい | OpenAPI JSONを中心に使いたい |
| 注意点 | PHPDocや設定の整備が必要 | 型定義やリソース設計に依存する |
関係者へのAPI仕様共有を考えるなら、まずはScribeが分かりやすそうです。
一方で、OpenAPIを中心に外部ツールやCI/CDとつなげたい場合は、Scrambleも候補になると思います。
どちらも「導入すればすべて自動で解決する」というより、既存コードの設計や型定義の整備状況によって出力品質が変わる点に注意が必要です。
提案してみた結果
ScribeとScrambleの概要、導入手順、注意点を資料にまとめ、API仕様共有の改善案として提案しました。
技術的には、APIドキュメントを自動生成することで、仕様確認や関係者への共有コストを下げられる可能性があると考えていました。
ただ、結果としてこの提案は実現には至りませんでした。
振り返ると、提案内容そのものよりも、伝え方に課題があったと思います。
当時は、ScribeやScrambleの機能、導入手順、生成できるドキュメントの内容を中心に説明していました。
しかし、本来伝えるべきだったのは「どのツールが便利か」ではなく、「API仕様共有にどのようなコストが発生していて、それを解消するとどのような効果があるのか」でした。
ツールの紹介としては成立していましたが、改善提案としては判断材料が足りませんでした。
特に足りなかったのは、以下の観点です。
- 現在どれくらい仕様確認のコストが発生しているか
- 誰の作業負担が増えているか
- 仕様認識のズレによってどのようなリスクがあるか
- 導入するとどの作業がどれくらい減るのか
- 導入時にどの程度の工数が必要か
- 導入後の運用ルールをどうするか
技術的に良さそうなツールを見つけても、それだけでは提案は通りません。
「便利そう」ではなく、「今の課題に対して、導入するだけの価値がある」と判断してもらえる形にする必要がありました。
次にやるなら
次に同じような提案をするなら、以下をやります。
1. 連携コストを数字にする
「API設計書がなくて困っています」だけだと、現場の改善要望に見えます。
次に提案するなら、以下のような情報を先に整理します。
- 仕様確認に何分かかっているか
- 誰に確認が集中しているか
- 同じ質問が何度発生しているか
- API変更時の連絡にどれくらい時間がかかっているか
- 仕様差分による手戻りが発生しているか
課題を感覚ではなく数字で示せると、改善の優先度を判断してもらいやすくなります。
2. 小さくデモを作る
全APIに導入する話だと大きくなりすぎます。
まずは代表的なAPIを1つ選んで、実際にScribeかScrambleでドキュメントを生成するのが良さそうです。
導入手順を説明するだけではなく、以下を見せるべきでした。
- 関係者にどう見せられるか
- 問い合わせ時にどこを見ればよいか
- リクエストやレスポンス例がどう表示されるか
- API変更時にどこが更新されるか
- 既存の確認フローと比べて何が楽になるか
実物があると、導入後のイメージを持ってもらいやすくなります。
3. 相手ごとに伝え方を変える
技術者にとっては、ScribeとScrambleの違いや導入手順が重要です。
一方で、PMやPdMにとって重要なのは、ツールの細かい機能よりも、導入することで何が改善されるかです。
PMには、導入工数、スケジュール影響、運用フローを伝える必要があります。
PdMやビジネス側には、顧客連携の品質、問い合わせ削減、仕様認識のズレによるリスク低減を伝える必要があります。
同じ資料をそのまま渡すのではなく、相手が判断しやすい形に変換するべきでした。
4. ツール紹介ではなく、課題解決として提案する
今回の反省として、提案の中心が「ScribeやScrambleを使うとAPIドキュメントを生成できる」というツール紹介寄りになっていました。
しかし、本来の課題はツール導入ではなく、API仕様共有のコストや仕様認識のズレを減らすことです。
次に提案するなら、まず以下のように伝えたいです。
- 現状、API仕様確認に手間がかかっている
- 仕様の確認先が実装者に集中している
- 仕様変更時の連携コストが高い
- ドキュメント自動生成により、確認先を分散できる
- 仕様共有の品質を一定にできる
- 結果として、関係者間の認識ズレや手戻りを減らせる
そのうえで、解決策の候補としてScribeやScrambleを提示する流れにした方が、提案として伝わりやすかったと思います。
まとめ
LaravelのAPIドキュメント自動生成ツールとして、ScribeとScrambleを調査しました。
関係者へ読みやすいAPIドキュメントを共有する用途ではScribeが扱いやすく、OpenAPIを中心に外部ツールと連携したい場合はScrambleが候補になります。
技術的には、API仕様共有のコストを下げる手段として有効そうだと感じました。
ただし、今回の提案は実現には至りませんでした。
振り返ると、ツールの調査や比較だけでなく、現状の課題、発生しているコスト、導入後の効果、必要な工数、運用方法まで整理して伝える必要がありました。
技術的に良い提案でも、意思決定に必要な材料が足りなければ前には進みません。
次に同じような改善提案をする場合は、ツール紹介ではなく、課題と効果を中心に伝えたいです。
そして、可能であれば小さなデモを作り、「これを導入すると何がどう楽になるのか」まで見える形で提案したいと思います。
参考
- Scribe: https://scribe.knuckles.wtf/laravel
- Scramble: https://scramble.dedoc.co/