APIを開発していると、
- ドキュメントが更新されない
- 実装と仕様がずれていく
- フロントエンドとの認識合わせが大変
といった課題が出てきます。
そこで便利なのが、APIドキュメントを自動生成するツールです。
Laravelでは代表的なものとして、
- Scribe
- Scramble
があります。
どちらもOpenAPI（Swagger）対応ですが、考え方や使い勝手には違いがあります。
この記事では、それぞれの特徴や使って感じたことを紹介します。
Scribeとは
ScribeはLaravel向けのAPIドキュメント生成ツールです。
ControllerやPHPDoc、Attributeなどから情報を取得し、
- API一覧
- リクエスト例
- レスポンス例
- 認証方法
などを含むドキュメントを生成できます。
インストール
composer require --dev knuckleswtf/scribe
生成
php artisan scribe:generate
HTMLドキュメントやOpenAPIファイルを出力できます。
Scrambleとは
ScrambleもLaravel向けのAPIドキュメント生成ツールですが、
Laravelのコードや型情報を解析して、OpenAPI仕様を生成することに特化しています。
インストール
composer require --dev dedoc/scramble
インストール後は、
/docs/api
などからSwagger UIを表示できます。
ControllerやFormRequest、Resourceなどを解析して、自動的に仕様を生成してくれます。
大きな違い
Scribe
Scribeは
「見やすいAPIドキュメントを作る」
ことに重点を置いています。
例えば、
- APIの説明
- サンプルリクエスト
- curl例
- JavaScript例
- PHP例
なども生成されます。
フロントエンドや外部利用者向けのドキュメントとして使いやすい印象でした。
Scramble
Scrambleは
「LaravelのコードからOpenAPIを生成する」
ことを重視しています。
Controllerや型定義から解析するため、
ドキュメントを書く量を減らせます。
Laravelらしい書き方との相性も良く、コードと仕様の差分が出にくいと感じました。
比較
| 項目 | Scribe | Scramble |
|---|---|---|
| ドキュメントの見やすさ | ◎ | ○ |
| OpenAPI対応 | ○ | ◎ |
| Laravelとの親和性 | ○ | ◎ |
| コメントを書く量 | やや多い | 少ない |
| 学習コスト | 低め | 低め |
実際に使って感じたこと
Scribe
Scribeは、
APIを利用する人へ見せるドキュメントとして非常に見やすい印象でした。
サンプルコードも自動生成されるため、
外部公開APIとの相性が良いと感じました。
一方で、
細かい説明を書きたい場合は、コメントやAttributeを追加する場面もあります。
Scramble
Scrambleは、
Laravelらしい書き方をしていれば、
かなり自然にOpenAPIを生成してくれます。
FormRequestやAPI Resourceを利用しているプロジェクトでは、
追加作業が少なく済む印象でした。
GitHub Actionsにも組み込める
どちらもCIで実行できます。
例えばScribeなら、
- name: Generate API Docs
run: php artisan scribe:generate
Scrambleなら、
OpenAPI生成後に成果物を公開する運用もできます。
これにより、
API仕様を手動で更新する必要がなくなります。
どちらを選ぶ？
個人的には、
Scribe
- API利用者向けのドキュメントを公開したい
- サンプルコードも充実させたい
- ドキュメントを読みやすくしたい
場合に向いていると思います。
Scramble
- OpenAPIを生成したい
- Laravelのコードから自動生成したい
- 実装と仕様の差分を減らしたい
場合に向いていると感じました。
まとめ
ScribeとScrambleは、どちらもLaravelでAPIドキュメントを自動生成できる便利なツールです。
ただし、目的は少し異なります。
- Scribe：読みやすいAPIドキュメントを作りたい場合に向いている
- Scramble：LaravelのコードからOpenAPIを自動生成したい場合に向いている
どちらを選ぶかは、APIの利用者や運用方法によって変わります。
APIドキュメントを手作業で更新している場合は、どちらかを導入するだけでも実装と仕様のズレを減らし、保守性を高められると感じました。