Scribe cho Laravel: Tạo tài liệu API tự động, đẹp, có “Try It Out”

Vì sao mình chọn Scribe?

Giao diện đẹp, 1 trang là thấy hết, có code sample và nút “Try It Out”.
Tự động hiểu validation, FormRequest, API Resource để gợi ý tham số và sample response.
Xuất Postman collection và OpenAPI spec để import vào Postman/Insomnia.
Tùy biến mạnh: UI, văn bản, thứ tự sections, chiến lược trích xuất dữ liệu.

Tài liệu chính thức rất rõ ràng để bắt đầu: Introduction, Getting started, Generating Docs, Customising features.

Bắt đầu: cài đặt nhanh

Cài package (mình thường để dev):

composer require --dev knuckleswtf/scribe

Publish file cấu hình:

php artisan vendor:publish --provider="Knuckles\\\\Scribe\\\\ScribeServiceProvider" --tag=scribe-config

Sau bước này, bạn sẽ có config/scribe.php để chỉnh toàn bộ hành vi và giao diện docs.

Chọn kiểu build docs: static hay laravel?

Trong config/scribe.php, đặt key type:

static: build ra public/docs/index.html + assets, không qua middleware.
laravel: render bằng Blade, có thể gắn auth/middleware, URL do bạn định nghĩa.

Gợi ý nhanh:

Docs nội bộ hoặc cần auth → laravel.
Public docs đơn giản, dễ deploy ở bất kỳ đâu → static.

Chọn routes sẽ được đưa vào docs

Cũng trong scribe.php, phần routes:

match.prefixes thường để api/* nếu API của bạn theo convention.
include và exclude để thêm/bớt cụ thể endpoint.

Ví dụ rút gọn:

'routes' => [[ 'match' => [ 'domains' => ['*'], 'prefixes' => ['api/*'], 'versions' => ['v1'], ], 'include' => [ // 'users.index', 'healthcheck*' ], 'exclude' => [ // '/health', 'admin.*' ],
]],

Thêm “gia vị” ngay trong code: annotations cho Scribe

Scribe “đọc” controller/route handler để suy luận thông tin. Bạn có thể annotate để docs “có hồn” hơn: tiêu đề, mô tả, ví dụ response, giải thích field…

Ví dụ “healthcheck”:

/** * Healthcheck * * Check that the service is up. If everything is okay, you'll get a 200 OK response. * * @response 400 scenario="Service is unhealthy" {"status":"down","services":{"database":"up","redis":"down"}} * @responseField status The status of this API (`up` or `down`). * @responseField services Map of each downstream service and their status (`up` or `down`). */
Route::get('/healthcheck', function () { return ['status' => 'up', 'services' => ['database' => 'up', 'redis' => 'up']];
});

Tuỳ biến phần “giới thiệu API”

Trong config/scribe.php, bạn có thể đặt:

title: tên hiển thị trên docs, đồng thời dùng cho Postman/OpenAPI.
description và intro_text: đoạn giới thiệu API.
base_url: URL hiển thị trong docs.
Thông tin authentication: header, token demo…

Bật “Try It Out” để test ngay trong trình duyệt

try_it_out.enabled = true
try_it_out.base_url: trỏ tới URL staging/local bạn muốn test.
Nếu API dùng Sanctum/SPAs: bật try_it_out.use_csrf = true để tự lấy cookie và đính kèm X-XSRF-TOKEN.

Nhớ bật CORS cho API để “Try It Out” chạy trơn tru.

Xuất Postman collection và OpenAPI

Bật trong scribe.php:

'postman' => ['enabled' => true, 'overrides' => [ // 'info.version' => '2.0.0',
]],
'openapi' => ['enabled' => true, 'overrides' => [ // 'info.version' => '2.0.0',
]],

Sau khi generate, menu docs sẽ có link tải về cho team import vào Postman/Insomnia.

Generate tài liệu: “bấm nút” là có

Chạy:

php artisan scribe:generate

static: HTML + assets ở public/docs.
laravel: Blade ở resources/views/scribe/index.blade.php.
Postman collection + OpenAPI spec nằm ở /content/images/app/scribe/.
Scribe tạo thư mục .scribe chứa data trung gian để bạn chỉnh tay nếu cần.

Mẹo: có thể dùng --env để load .env.docs, ví dụ tắt notification khi Scribe gọi endpoint để lấy sample response.

Demo và cảm nhận nhanh

Giao diện “đã mắt”, code sample rõ ràng, sidebar mạch lạc.
Áp dụng thực tế: dev đỡ hỏi “endpoint X cần header gì”, PM/QA test nhanh, khách hàng thấy chuyên nghiệp hơn hẳn.

Checklist “xong là ship”

[ ] Cài và publish config
[ ] Chọn type static/laravel
[ ] Cấu hình routes đúng phạm vi API
[ ] Viết mô tả tổng quan, auth, base_url trong scribe.php
[ ] Thêm annotations cho endpoint quan trọng
[ ] Bật Try It Out + CORS
[ ] Bật Postman + OpenAPI
[ ] php artisan scribe:generate
[ ] Commit .scribe nếu muốn kiểm soát nội dung docs
[ ] Deploy docs và chia sẻ link cho team

Troubleshooting nhanh

Try It Out báo lỗi CORS → kiểm tra CORS middleware.
Không thấy endpoint → soát match.prefixes hoặc include/exclude.
Postman/OpenAPI không update → đảm bảo enabled = true, clear cache trước khi kiểm tra lại.
Dùng Sanctum mà thử không chạy → bật use_csrf và đặt csrf_url đúng.