Scribe文档工具中隐藏Laravel资源路由的PATCH方法

在Laravel开发中，Route::resource会自动生成包含7种标准RESTful动作的路由，其中更新操作同时支持PUT和PATCH两种HTTP方法。但某些项目可能只需要保留其中一种方法，特别是在使用API文档生成工具Scribe时，开发者可能需要从文档中隐藏PATCH方法。

问题背景

Laravel的Route::resource会为update动作注册两个路由：

• PUT方法：完全替换资源
• PATCH方法：部分更新资源

虽然这两种方法在REST规范中有明确区分，但在实际业务中，很多项目可能只需要使用其中一种。当使用Scribe生成API文档时，开发者可能希望隐藏不需要的方法以保持文档简洁。

解决方案

方法一：修改路由定义（推荐）

最根本的解决方案是在路由定义阶段就排除不需要的方法。Laravel提供了only和except方法来筛选资源控制器的方法：

// 只保留需要的动作
Route::resource('photos', PhotoController::class)->only([
    'index', 'show', 'store', 'update' // 这里update将只注册PUT方法
]);

// 或者排除不需要的动作
Route::resource('photos', PhotoController::class)->except([
    'destroy' // 排除特定方法
]);

这种方式从源头解决问题，生成的文档自然只包含定义的路由。

方法二：Scribe配置排除

如果必须保留路由但只需要在文档中隐藏，可以在Scribe配置文件中设置：

// config/scribe.php
'routes' => [
    'exclude' => [ 
        'PATCH /api/photos/*', // 精确排除PATCH方法
    ],
],

需要注意的是，这种方式可能在某些版本中会同时影响PUT方法，因为Scribe依赖Laravel的路由信息。

最佳实践建议

1. 优先考虑路由定义：在路由层面解决问题比后期过滤更可靠
2. 保持一致性：整个项目应该统一使用PUT或PATCH中的一种
3. 文档说明：在API文档中明确说明支持的更新方法
4. 测试验证：修改后应测试实际接口和文档是否如预期工作

技术原理

Scribe通过分析Laravel路由系统生成文档。Route::resource在底层会注册多个路由，每个对应不同的HTTP方法。当开发者需要定制文档时，理解这一机制很重要：

1. Laravel路由系统首先注册所有资源路由
2. Scribe通过反射和路由收集器获取这些信息
3. 排除配置在文档生成阶段过滤路由

因此，在路由定义阶段处理是最有效的方式，可以避免后续工具的复杂性。

通过以上方法，开发者可以灵活控制API文档中展示的路由方法，保持文档的清晰和准确。