Laravelで手軽にAPIドキュメントを生成する ― Scribe活用術

Laravel Live Japan 2026 の発表資料です。

Transcript

1. Laravelで手軽にAPIドキュメントを生成する ― Scribe活用術 Laravel Live Japan 2026 2026/05/26 SAW
2. $(whoami) ハンドルネーム: SAW 氏名: 加藤 宗一郎 : @azuki_eater 所属: ゴールドスポンサー 2 Laravel Live Japan 2026
3. Laravel で Web API を作ったことはありますか? Laravel Live Japan 2026 3
4. その Web API にドキュメントはありますか? Laravel Live Japan 2026 4
5. そのドキュメントはちゃんと更新されていますか? Laravel Live Japan 2026 5
6. Scribe はとても良い解決策になります Laravel Live Japan 2026 6
7. Scribe とは? API ドキュメントを生成するための Laravel のライブラリ 理解しやすく実際に動かせる Web UI OpenAPI 仕様書や Postman collection の生成が可能 Laravel 特化の機能 7 Laravel Live Japan 2026
8. インストール方法 1. Composer 経由でインストール 2. 設定ファイルを生成 前提条件 PHP 8.1 以上 Laravel 9 以上 composer require knuckleswtf/scribe php artisan vendor:publish --tag=scribe-config 8 Laravel Live Japan 2026
9. 最もシンプルな使い方 1. routes/api.php に API の route を定義 2. php artisan scribe:generate を実行してドキュメントを生成 /docs から生成されたドキュメントが確認可能 Route::get('/sample', [SampleController::class, 'sample']); Laravel Live Japan 2026 9
10. リクエストやレスポンスの情報を追加したい場合は? Laravel Live Japan 2026 10
11. リクエストボディの情報の追加 1. Laravel のリクエストのバリデーション機能を追加 2. php artisan scribe:generate を実行 $validated = $request->validate([ 'message' => ['required'], ]); Laravel Live Japan 2026 11
12. レスポンスの出力例を追加 1. 出力例を生成する対象を config/scribe.php で設定 only 引数で対象とするエンドポイントを指定 only 引数を省略するとすべてのエンドポイントが対象 2. php artisan scribe:generate を実行 'responses' => configureStrategy( Defaults::RESPONSES_STRATEGIES, Strategies\Responses\ResponseCalls::withSettings( only: ['GET *'], config: ['app.debug' => false], ), ), Laravel Live Japan 2026 12
13. レスポンスの出力例を追加 1. 出力例を生成する対象を config/scribe.php で設定 only 引数で対象とするエンドポイントを指定 only 引数を省略するとすべてのエンドポイントが対象 2. php artisan scribe:generate を実行 only: ['GET *'], 'responses' => configureStrategy( Defaults::RESPONSES_STRATEGIES, Strategies\Responses\ResponseCalls::withSettings( config: ['app.debug' => false], ), ), Laravel Live Japan 2026 12
14. レスポンスの出力例を追加 1. 出力例を生成する対象を config/scribe.php で設定 only 引数で対象とするエンドポイントを指定 only 引数を省略するとすべてのエンドポイントが対象 2. php artisan scribe:generate を実行 only: ['GET *', 'POST *'], 'responses' => configureStrategy( Defaults::RESPONSES_STRATEGIES, Strategies\Responses\ResponseCalls::withSettings( config: ['app.debug' => false], ), ), Laravel Live Japan 2026 12
15. レスポンスの出力例を追加 1. 出力例を生成する対象を config/scribe.php で設定 only 引数で対象とするエンドポイントを指定 only 引数を省略するとすべてのエンドポイントが対象 2. php artisan scribe:generate を実行 'responses' => configureStrategy( Defaults::RESPONSES_STRATEGIES, Strategies\Responses\ResponseCalls::withSettings( config: ['app.debug' => false], ), ), Laravel Live Japan 2026 12
16. コードをほぼ追加せずにドキュメントを生成できた! Laravel Live Japan 2026 13
17. その他の機能 #[Endpoint()] : エンドポイントのタイトルや説明を追加 #[UrlParam()] : URL パラメーターの詳細を追加 #[QueryParam()] , #[BodyParam()] : クエリパラメタやリクエストボディの詳細を追加 #[ResponseFromApiResource()] : ApiResource からレスポンス例を生成 etc… public function find(int $id): SampleMessageResource { $message = SampleMessage::findOrFail($id); return new SampleMessageResource($message); } Laravel Live Japan 2026 14
18. その他の機能 #[Endpoint()] : エンドポイントのタイトルや説明を追加 #[UrlParam()] : URL パラメーターの詳細を追加 #[QueryParam()] , #[BodyParam()] : クエリパラメタやリクエストボディの詳細を追加 #[ResponseFromApiResource()] : ApiResource からレスポンス例を生成 etc… #[Endpoint('Find The Sample Message', 'Return the sample message.')] public function find(int $id): SampleMessageResource { $message = SampleMessage::findOrFail($id); return new SampleMessageResource($message); } Laravel Live Japan 2026 14
19. その他の機能 #[Endpoint()] : エンドポイントのタイトルや説明を追加 #[UrlParam()] : URL パラメーターの詳細を追加 #[QueryParam()] , #[BodyParam()] : クエリパラメタやリクエストボディの詳細を追加 #[ResponseFromApiResource()] : ApiResource からレスポンス例を生成 etc… #[UrlParam('id', 'integer', 'The ID of the message.')] public function find(int $id): SampleMessageResource #[Endpoint('Find The Sample Message', 'Return the sample message.')] { $message = SampleMessage::findOrFail($id); return new SampleMessageResource($message); } Laravel Live Japan 2026 14
20. その他の機能 #[Endpoint()] : エンドポイントのタイトルや説明を追加 #[UrlParam()] : URL パラメーターの詳細を追加 #[QueryParam()] , #[BodyParam()] : クエリパラメタやリクエストボディの詳細を追加 #[ResponseFromApiResource()] : ApiResource からレスポンス例を生成 etc… #[ResponseFromApiResource(SampleMessageResource::class, SampleMessage::class)] return new SampleMessageResource($message); #[Endpoint('Find The Sample Message', 'Return the sample message.')] #[UrlParam('id', 'integer', 'The ID of the message.')] public function find(int $id): SampleMessageResource { $message = SampleMessage::findOrFail($id); } Laravel Live Japan 2026 14
21. その他の機能 #[Endpoint()] : エンドポイントのタイトルや説明を追加 #[UrlParam()] : URL パラメーターの詳細を追加 #[QueryParam()] , #[BodyParam()] : クエリパラメタやリクエストボディの詳細を追加 #[ResponseFromApiResource()] : ApiResource からレスポンス例を生成 etc… #[Endpoint('Find The Sample Message', 'Return the sample message.')] #[UrlParam('id', 'integer', 'The ID of the message.')] #[ResponseFromApiResource(SampleMessageResource::class, SampleMessage::class)] public function find(int $id): SampleMessageResource { $message = SampleMessage::findOrFail($id); return new SampleMessageResource($message); } Laravel Live Japan 2026 14
22. 生成結果 15 Laravel Live Japan 2026
23. まとめ Scribe について説明 手軽にAPIドキュメントを生成する Scribe 活用術 より詳細な機能の紹介 16 Laravel Live Japan 2026
24. Scribe の世界に飛び込んでみよう! Laravel Live Japan 2026 17
25. ご清聴ありがとうございました Laravel Live Japan 2026