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

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

composer require --dev knuckleswtf/scribe

2. 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 ở storage/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.

Nguồn tham khảo

• Scribe Docs – Introduction

• Scribe Docs – Getting started

• Scribe Docs – Generating Docs

• Scribe Docs – Customising features

• Scribe Docs – General API info

• Demo Scribe