Scramble项目中ExcludeAllRoutesFromDocs属性的正确使用方式

Scramble作为一款优秀的Laravel API文档生成工具，提供了多种方式来控制路由文档的生成行为。其中ExcludeAllRoutesFromDocs属性是一个非常有用的功能，但需要特别注意其使用场景和方法。

属性功能解析

ExcludeAllRoutesFromDocs属性设计用于控制器类级别，而非单个方法。它的作用是排除该控制器中定义的所有路由，使其不会出现在生成的API文档中。这个特性特别适合那些内部使用或不需要公开文档的API端点。

常见错误用法

许多开发者容易犯的一个错误是尝试在单个路由方法上使用ExcludeAllRoutesFromDocs属性，如：

#[ExcludeAllRoutesFromDocs]
public function webhook(WebhookInvoiceData $data, Request $request): Response
{
    // 方法实现
}

这种用法会导致Larastan静态分析工具报错，提示"Attribute class does not have the method target"，因为该属性实际上并不支持方法级别的应用。

正确使用方式

正确的做法是将ExcludeAllRoutesFromDocs应用于整个控制器类：

#[ExcludeAllRoutesFromDocs]
class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        // 控制器方法
    }
    
    public function callback(Request $request)
    {
        // 另一个控制器方法
    }
}

这样，该控制器下的所有路由都将被排除在API文档之外。

替代方案：方法级排除

如果只需要排除特定路由而非整个控制器的所有路由，应该使用ExcludeRouteFromDocs属性：

class MixedController extends Controller
{
    #[ExcludeRouteFromDocs]
    public function internalApi()
    {
        // 这个方法不会出现在文档中
    }
    
    public function publicApi()
    {
        // 这个方法会正常出现在文档中
    }
}

最佳实践建议

1. 对于完全内部使用的API控制器，使用类级别的ExcludeAllRoutesFromDocs
2. 对于混合使用的控制器，选择性使用方法级别的ExcludeRouteFromDocs
3. 在团队开发中，建议在项目文档中明确标注这些属性的使用规范
4. 结合Laravel的路由分组功能，可以更灵活地控制文档生成范围

理解这些属性的正确使用方式，可以帮助开发者更精确地控制API文档的生成范围，避免不必要的信息泄露，同时保持文档的清晰性和准确性。