Effortless API Documentation with Scribe

A presentation slide of Laravel Live Japan 2026

Transcript

1. Effortless API Documentation with Scribe Laravel Live Japan 2026 2026/05/26 SAW
2. $(whoami) Nickname: SAW Name: Soichiro Kato : @azuki_eater Company: Gold Sponsor 2 Laravel Live Japan 2026
3. Do you have Web APIs built with Laravel? Laravel Live Japan 2026 3
4. Do your Web APIs have documentation? Laravel Live Japan 2026 4
5. Is your documentation kept up to date? Laravel Live Japan 2026 5
6. Scribe is a great solution. Laravel Live Japan 2026 6
7. What Is Scribe? A library to help generate API documentation Human-friendly and interactive Web UI OpenAPI spec and Postman collection Laravel-specific features 7 Laravel Live Japan 2026
8. Installation 1. Install the Scribe package with Composer 2. Publish the Scribe config file Prerequisite PHP 8.1 or higher Laravel 9 or higher composer require knuckleswtf/scribe php artisan vendor:publish --tag=scribe-config 8 Laravel Live Japan 2026
9. The Simplest Usage 1. Define API routes in routes/api.php . 2. Run the document generation command php artisan scribe:generate . Access /docs after the command finishes. Route::get('/sample', [SampleController::class, 'sample']); Laravel Live Japan 2026 9
10. Do you want to add request and response information? Laravel Live Japan 2026 10
11. Add Request Body Information 1. Add Laravel’s request validation feature. 2. Run the document generation command php artisan scribe:generate . $validated = $request->validate([ 'message' => ['required'], ]); Laravel Live Japan 2026 11
12. Add Response Examples 1. Adjust config/scribe.php to generate example responses automatically. add items to the only parameter to specify which endpoints Scribe should call remove the only parameter to allow Scribe to call all endpoints 2. Run the document generation command 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. Add Response Examples 1. Adjust config/scribe.php to generate example responses automatically. add items to the only parameter to specify which endpoints Scribe should call remove the only parameter to allow Scribe to call all endpoints 2. Run the document generation command 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. Add Response Examples 1. Adjust config/scribe.php to generate example responses automatically. add items to the only parameter to specify which endpoints Scribe should call remove the only parameter to allow Scribe to call all endpoints 2. Run the document generation command 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. Add Response Examples 1. Adjust config/scribe.php to generate example responses automatically. add items to the only parameter to specify which endpoints Scribe should call remove the only parameter to allow Scribe to call all endpoints 2. Run the document generation command php artisan scribe:generate . 'responses' => configureStrategy( Defaults::RESPONSES_STRATEGIES, Strategies\Responses\ResponseCalls::withSettings( config: ['app.debug' => false], ), ), Laravel Live Japan 2026 12
16. Almost no documentation-only code! Laravel Live Japan 2026 13
17. Other Powerful Scribe Features #[Endpoint()] : Add an endpoint description #[UrlParam()] : Add details for a URL parameter #[QueryParam()] , #[BodyParam()] : Add query and body parameter details #[ResponseFromApiResource()] : Generate a response example from ApiResource and more… public function find(int $id): SampleMessageResource { $message = SampleMessage::findOrFail($id); return new SampleMessageResource($message); } Laravel Live Japan 2026 14
18. Other Powerful Scribe Features #[Endpoint()] : Add an endpoint description #[UrlParam()] : Add details for a URL parameter #[QueryParam()] , #[BodyParam()] : Add query and body parameter details #[ResponseFromApiResource()] : Generate a response example from ApiResource and more… #[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. Other Powerful Scribe Features #[Endpoint()] : Add an endpoint description #[UrlParam()] : Add details for a URL parameter #[QueryParam()] , #[BodyParam()] : Add query and body parameter details #[ResponseFromApiResource()] : Generate a response example from ApiResource and more… #[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. Other Powerful Scribe Features #[Endpoint()] : Add an endpoint description #[UrlParam()] : Add details for a URL parameter #[QueryParam()] , #[BodyParam()] : Add query and body parameter details #[ResponseFromApiResource()] : Generate a response example from ApiResource and more… #[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. Other Powerful Scribe Features #[Endpoint()] : Add an endpoint description #[UrlParam()] : Add details for a URL parameter #[QueryParam()] , #[BodyParam()] : Add query and body parameter details #[ResponseFromApiResource()] : Generate a response example from ApiResource and more… #[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. Generated Results 15 Laravel Live Japan 2026
23. Summary What is Scribe Effortless API documentation with Scribe Powerful Scribe Features 16 Laravel Live Japan 2026
24. Let’s dive into Scribe! Laravel Live Japan 2026 17
25. Thank you! Laravel Live Japan 2026