如何在Scramble中自定义Fortify认证路由的API文档

背景介绍

Scramble是一个为Laravel应用自动生成API文档的工具。当与Laravel Fortify(一个提供用户认证功能的官方包)集成时，开发者可能会遇到自动生成的API文档不完整或不符合需求的情况。

常见问题

许多开发者发现Fortify自动生成的登录路由文档工作正常，但注册路由的文档却缺失。这是因为Scramble默认可能无法识别Fortify的所有路由和请求类型。

解决方案

要解决这个问题，我们可以通过自定义方式来完善Fortify路由的API文档。以下是具体实现方法：

1. 创建自定义请求类

首先，为注册功能创建一个自定义的FormRequest类：

namespace App\Http\Requests\Auth;

use Illuminate\Foundation\Http\FormRequest;

class RegisterRequest extends FormRequest
{
    public function rules()
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'string', 'email', 'max:255', 'unique:users'],
            'password' => ['required', 'string', 'confirmed', 'min:8'],
        ];
    }
}

2. 覆盖Fortify的默认行为

在Fortify服务提供者中，重写注册路由的处理逻辑：

namespace App\Providers;

use App\Http\Requests\Auth\RegisterRequest;
use Laravel\Fortify\Fortify;
use Illuminate\Support\ServiceProvider;

class FortifyServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Fortify::register(function (RegisterRequest $request) {
            // 注册逻辑
        });
    }
}

3. 配置Scramble识别自定义路由

为了让Scramble能够正确识别这些路由，可以在文档生成配置中添加相应的路由信息：

// config/scramble.php
return [
    'routes' => [
        [
            'path' => '/register',
            'method' => 'POST',
            'request' => \App\Http\Requests\Auth\RegisterRequest::class,
        ],
    ],
];

进阶技巧

1. 响应类型定义：除了请求参数，还可以定义响应的数据结构
2. 错误响应：添加各种错误情况的响应示例
3. 认证头：如果需要，可以添加认证相关的头信息说明

最佳实践

• 为每个Fortify路由创建专门的请求类
• 在请求类中详细定义所有验证规则
• 使用Scramble的注释功能增强文档可读性
• 定期检查生成的文档是否符合预期

通过以上方法，开发者可以完全控制Fortify路由在API文档中的表现，确保文档的完整性和准确性。