README

面向 Mitoop 生态业务接口约定的 Scramble (OpenAPI 文档生成器) 适配包。

这个包不是通用 Scramble 扩展。它服务于使用 mitoop/laravel-api-response、mitoop/laravel-efficient-form-request、mitoop/laravel-query-builder 的项目，把这些业务约定补充到 Scramble 生成的 OpenAPI 文档中。

兼容性

Package	Version
PHP	`^8.3`
Laravel	`^13.0`
Scramble	`^0.13.30`

旧版 Laravel/Scramble 项目请继续使用本包 v0.2.x。

主要功能：

自动将 200 响应包装为统一的业务信封结构 {success, code, message, data, [meta], request_id}
支持场景化表单请求 (Scene FormRequest) 的参数提取
支持 Filter 查询参数自动提取（筛选字段、排序、分页）
支持读取数据库字段注释并写入 OpenAPI schema description

各功能模块均可通过配置文件独立开启或关闭；未安装对应 Mitoop 包时，对应模块会自动跳过。

安装

composer require admin9/laravel-scramble-extensions

发布配置文件：

php artisan vendor:publish --tag=scramble-extensions-config

可选依赖

根据你使用的 Mitoop 约定，按需安装对应的包：

# 业务响应信封包装
composer require mitoop/laravel-api-response

# 场景化表单请求
composer require mitoop/laravel-efficient-form-request

# Filter 查询参数提取
composer require mitoop/laravel-query-builder

配置

配置文件 config/scramble-extensions.php：

return [
    'response' => [
        'enabled' => true,
        // 控制器需要 use 的 trait，提供 $this->success() 等方法
        'trait' => 'Mitoop\\Http\\RespondsWithJson',
        // 模型命名空间，用于分页响应自动推断模型
        'model_namespace' => 'App\\Models',
        // 从数据库字段注释生成 schema description
        'column_comments' => true,
        // 修正业务响应 data 内 Scramble 无法精确推断的字段 schema
        // 当前支持：string_list
        'schema_overrides' => [],
    ],

    'scene_form_request' => [
        'enabled' => true,
    ],

    'filter' => [
        'enabled' => true,
        'pagination' => [
            'page_size_default' => 15,
            'page_size_max' => 100,
        ],
    ],
];

功能说明

1. 业务响应信封包装 (Response)

自动将所有 200 响应包装为统一的业务信封结构。

控制器需要 use 配置中指定的 Mitoop trait（默认 Mitoop\Http\RespondsWithJson），通过 $this->success()、$this->error()、$this->deny() 返回响应。

class UserController extends Controller
{
    use \Mitoop\Http\RespondsWithJson;

    public function show(User $user)
    {
        return $this->success($user);
    }

    public function index()
    {
        return $this->success(User::paginate());
    }
}

生成的 OpenAPI 文档中，标准响应结构为：

{
  "success": true,
  "code": 0,
  "message": "",
  "data": { ... },
  "request_id": "uuid7"
}

分页响应会额外包含 meta 字段：

{
  "success": true,
  "code": 0,
  "message": "",
  "data": [ ... ],
  "meta": {
    "pagination": "length_aware",
    "page": 1,
    "page_size": 15,
    "has_more": true,
    "total": 100
  },
  "request_id": "uuid7"
}

如果 Scramble 对某些业务响应字段推断过宽，可以通过 schema_overrides 收敛字段 schema：

'response' => [
    'schema_overrides' => [
        'permission_names' => 'string_list',
    ],
],

string_list 会生成 {"type":"array","items":{"type":"string"}}，适合权限名、标签名等字符串列表字段。

2. 场景化表单请求提取 (Scene FormRequest)

支持 mitoop/laravel-efficient-form-request，允许同一个 FormRequest 根据控制器方法名定义不同的验证规则。

扩展会自动查找 FormRequest 上的 {actionName}Rules() 方法并提取参数到 OpenAPI 文档。

use Mitoop\LaravelEfficientFormRequest\EfficientSceneFormRequest;

class UserRequest extends EfficientSceneFormRequest
{
    // store 方法使用的规则
    public function storeRules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email',
        ];
    }

    // update 方法使用的规则
    public function updateRules(): array
    {
        return [
            'name' => 'string|max:255',
        ];
    }
}

class UserController extends Controller
{
    public function store(UserRequest $request) { ... }
    public function update(UserRequest $request, User $user) { ... }
}

store 接口文档会包含 name（必填）和 email（必填）参数，update 接口文档只包含 name 参数。

3. Filter 查询参数提取 (Filter)

支持 mitoop/laravel-query-builder，自动从 Filter 类中提取筛选字段、排序选项和分页参数到 OpenAPI 文档。

use Mitoop\LaravelQueryBuilder\AbstractFilter;

class UserFilter extends AbstractFilter
{
    protected array $allowedSorts = ['created_at', 'name'];

    public function rules(): array
    {
        return [
            'name',
            'email',
            'status',
        ];
    }
}

class UserController extends Controller
{
    public function index()
    {
        $users = User::filter(UserFilter::class)->paginate();

        return $this->success($users);
    }
}

生成的文档会自动包含以下 query 参数：

name、email、status — 筛选字段
sort — 排序字段，可选值 created_at、name，前缀 - 表示降序
page_size — 每页条数（默认 15，最大 100，可通过配置修改）
page — 页码

4. 模型字段注释 (Column Comments)

当模型字段在数据库 schema 中带有 comment 时，扩展会把 comment 写入对应 OpenAPI property 的 description。这用于让接口字段说明跟迁移/数据库字段注释保持一致。

该能力依赖数据库驱动能通过 Laravel schema builder 返回 comment 字段；不支持字段注释的驱动会安全跳过。

5. 显式业务 Schema 类型

在定制业务响应 schema 时，可以显式使用只读整数类型：

use Admin9\ScrambleExtensions\Schema\Types\ReadOnlyIntegerType;
use Dedoc\Scramble\Support\Generator\Types\ObjectType;

$schema = (new ObjectType)->addProperty('id', (new ReadOnlyIntegerType)->format('int64'));

生成的 id schema 包含标准 readOnly: true，并保留整数类型的约束。这只是文档声明，不会改变运行时验证或响应。

调用方可以在自己的 Scramble 类型子类中使用 Admin9\ScrambleExtensions\Schema\Concerns\ReadOnlySerialization trait，例如为字符串字段声明只读。trait 面向 Scramble 的类型序列化 API，兼容本包支持的旧序列化入口及 OpenAPI 3.1/3.2 入口。

这些类型用于显式定制业务契约，不自动推断只读字段。请直接保留子类实例；将属性通过 addProperties() 复制到普通类型不会复制子类的只读行为。

需要声明不接受额外字段的对象时，使用 ClosedObjectType：

use Admin9\ScrambleExtensions\Schema\Types\ClosedObjectType;
use Dedoc\Scramble\Support\Generator\Types\StringType;

$schema = (new ClosedObjectType)
    ->addProperty('name', new StringType)
    ->setRequired(['name']);

该对象输出标准 additionalProperties: false；嵌套对象如需关闭额外字段，也要显式使用 ClosedObjectType。已有属性、必填项和引用保持不变。它只影响文档，不替代请求验证。

不要同时设置 additionalProperties(new StringType) 等额外属性类型；这种矛盾配置会在序列化时抛出 LogicException。普通 ObjectType 仍支持带类型的额外属性。

License

MIT

admin9 / laravel-scramble-extensions

Package info

Security

Statistics