在记录 API 端点时，您可以将任务拆分为记录请求部分（身份验证、请求正文、请求参数）和记录响应部分。在本指南中，我们将深入探讨请求文档。
自动生成请求参数和主体
Scramble 的主要目标是生成尽可能多的 API 文档，而无需您手动编写任何注释。编写包含所有参数和请求主体的 PHPDoc 是一项繁琐且容易出错的任务。如果请求的某些细节发生变化，您就需要更新 PHPDoc。迟早会错过任何更正，导致 API 文档过时。
如果你仔细想想，就会发现代码库中已经包含了大量关于 API 请求的信息！验证规则、路由路径参数以及方法调用 $request——所有这些数据都描述了 API 端点的请求。
Scramble 使用此信息自动生成描述可发送到 API 的数据类型的基本请求文档。
使用模型绑定时，Scramble 会根据模型键的类型记录路径参数。正如预期的那样，整数键会被记录为整数，而 uuid 键则会记录为字符串， uuid 格式如下：
为参数添加描述和示例
除了 Scramble 生成的请求结构和参数之外，您还可以添加描述、示例和默认值。您还可以添加其他参数，以防 Scramble 出现遗漏或更改参数类型。
最简单的方法是使用属性：
#[BodyParameter('name', 'The name of the company')]public function store(Request $request){ $request->validate([ 'name' => ['required', 'string'], ]); ...}
您还可以使用规则上的 PHPDoc 注释为参数添加描述。
public function store(Request $request){ $request->validate([ // The name of the company. 'name' => ['required', 'string'], ]); ...}
#手动向单个端点添加参数
-------------------------------------------------------------------------------------------------------------------------------------------------------------
使用源代码作为请求 API 文档，Scramble 可以涵盖大多数情况。但是，它不会自动记录请求标头或 Cookie。
你可以使用属性来实现这一点。例如，假设你在控制器中检索一个 header 值，如下所示：
$request->header('X-Header-Name');
可以使用以下#[HeaderParameter]属性来记录：
#[HeaderParameter('X-Header-Name', 'The name of the header.', type: 'string')]
如果您想记录 cookie，您可以使用该#[CookieParameter]属性。
$value = $request->cookie('name');
像这样记录：
#[CookieParameter('name', 'The cookie.', type: 'string')]
使用#[PathParameter]、#[QueryParameter]和#[BodyParameter]，您还可以记录请求的相应参数。
要记录在查询字符串中发送到 API 的查询参数（例如/api/books?page=1），请使用以下#[QueryParameter]属性：
#[QueryParameter('page', 'The page number.', type: 'int')]
使用#[PathParameter]，你可以记录路由中的路径参数。例如，book路由中有一个 路径参数GET /api/book/{book}。
#[PathParameter('book', 'The book to show')]
如果需要添加请求体参数，请使用#[BodyParameter]属性。
#[BodyParameter('project_id', type: 'int')
您甚至可以像在验证规则中一样使用点来创建深层结构：
#[BodyParameter('projects.*.id', 'The ID of the project', type: 'int')]#[BodyParameter('projects.*.name', 'The name of the project', type: 'string')]
默认情况下，属性会将信息“附加”到从代码库自动推断出的参数上。要忽略自动推断的参数信息，请传递infer: false给该属性。这将仅保留手动提供的参数信息：
#[QueryParameter('page', 'The page number.', type: 'int', infer: false)]
#向多个端点添加参数文档
-------------------------------------------------------------------------------------------------------------------------------------------------------------------
通常，标头和 Cookie 会在中间件中检索，使其适用于所有端点。Scramble 允许您使用转换器完全控制生成的 OpenAPI 文档。
操作转换器允许您向所有端点添加额外的文档信息。您还可以检查中间件，并在路由上存在特定中间件时应用文档。
考虑这个例子。我们有一个全局中间件，用于记录从请求头中获取的请求 ID。每当任何 API 路由被触发时，这个中间件都会运行，因此我们希望为所有路由记录它。
<?php namespace App\Http\Middleware; use Closure;use Illuminate\Http\Request;use Symfony\Component\HttpFoundation\Response; class LogRequestId{ public function handle(Request $request, Closure $next): Response { if ($id = $request->header('X-Request-ID')) { info("Request ID: $id (url: {$request->url()}"); } return $next($request); }}
boot 现在，我们可以使用服务提供商的方法中的操作转换器将此标头添加到所有路由 ：
public function boot(): void{ Scramble::configure() ->withOperationTransformers(function (Operation $operation) { $operation->parameters[] = (new Parameter('X-Request-ID', 'header')) ->description('The ID of the request for better request visibility.') ->setSchema(Schema::fromType(new StringType)); });}
现在，X-Request-ID标头已添加到所有 API 路由。
#添加端点的标题和描述
---------------------------------------------------------------------------------------------------------------------------------------------------
为了提供更多端点上下文信息，您可以在其文档中添加标题和描述。只需添加 PHPDoc 注释即可。第一行将被视为端点标题，之后的行将被视为描述。您可以使用CommonMark Markdown 格式来添加描述。
#文件认证
---------------------------------------------------------------------------------------------------------------------------------
如果您的 API 需要身份验证，您可以使用文档转换器记录它并指定 API 的默认身份验证机制。
boot 文档转换器在服务提供商的方法中定义 ：
public function boot(){ Scramble::configure() ->withDocumentTransformers(function (OpenApi $openApi) { $openApi->secure( SecurityScheme::http('bearer') ); });}
如果端点是公共的（例如，用户注册），则可以将该端点标记为不需要身份验证：
/** * @unauthenticated */public function store(Request $request){ ...}
通过使用操作转换器，您甚至可以检查路由上的中间件，并自动删除没有auth中间件的端点的身份验证要求：
public function boot(){ Scramble::configure() ->withOperationTransformers(function (Operation $operation, RouteInfo $routeInfo) { $routeMiddleware = $routeInfo->route->gatherMiddleware(); $hasAuthMiddleware = collect($routeMiddleware)->contains( fn ($m) => Str::startsWith($m, 'auth:') ); if (! $hasAuthMiddleware) { $operation->security = []; } })}
#对端点进行分组并对组进行排序
---------------------------------------------------------------------------------------------------------------------------------------------------
要对端点进行分组，您可以使用#[Group]控制器上的属性（该属性将对该控制器的所有端点进行分组）和控制器的方法。
#[Group('Companies API')]class CompaniesController {...}
weight您可以通过向属性提供参数来对组进行排序#[Group]：
#[Group('Domains API', weight: 2)]class DomainsController {...}
＃结论
------------------------------------------------------------------------------------------------------------------
使用 Scramble，您可以根据源代码生成最新的 API 文档。这不仅节省时间，还能确保您的 API 文档保持准确性。此外，您还可以通过添加参数描述、标题、示例和默认值来增强文档，从而记录 API 的所有细节。
如果你还没有尝试过 Scramble，请尝试一下：https://scramble.dedoc.co
另外，请查看 Scramble 生成的演示文档：https://scramble.dedoc.co/demo/scramble。您将在文档中找到“转到 GitHub”链接，该链接可让您快速跳转到生成每个文档的源代码。