\App\SupportApiDocEnhancer

接口文档增强器

职责：在 Scramble 生成 OpenAPI 文档后完成四件事—— ① 文档首页注入项目 API 总览（响应包装/状态码/认证/限流/权限模型约定）； ② 字段描述分层注入：响应包装层、模型 Schema 层、请求 Schema 层各归其位，杜绝全局描述串位（如 company.code 被套上业务状态码说明）； ③ 语义增强：固定取值字段注入 enum 与 x-enumDescriptions、关键字段注入示例、标准错误响应以复用组件引用挂到每个接口； ④ 结构修正：分页 meta 字段类型、data.list 模型引用与缺失模型 Schema 补全、 store 请求 required 字段补全。

所有注册表集中在分区 8，是接口文档内容的唯一事实源；控制器注解与模型

Summary

Methods

Properties

Constants

handle()

ERROR_RESPONSES
PUBLIC_PATHS

No protected methods found

No protected properties found

N/A

loadRegistries()
applyInfoOverview()
configureSecurity()
registerErrorResponses()
attachErrorResponses()
describeSuccessResponses()
buildErrorResponse()
patchResponseEnvelopes()
patchEnvelope()
patchSpecialResponses()
jobStatusCountItems()
describeSkippedItems()
ensureModelSchemas()
buildModelType()
synchronizeModelSchema()
buildType()
buildItemsType()
buildObjectItemsType()
enhanceComponentSchemas()
applyRequestSchema()
applyFieldSemantics()
descFor()
enumFor()
exampleFor()
applyEnum()
applyExample()
enhanceInlineRequestBodies()
ensureConfigSaveRequestBody()
enhanceParameters()
enhanceSingleParameter()
fixStoreRequiredFields()
resolveInlineSchemaName()
overviewMarkdown()
wrapperDescriptions()
genericDescriptions()
fieldEnums()
fieldExamples()
modelSchemaDefinitions()
requestSchemaDescriptions()
parameterDescriptions()
pathParameterDescriptions()
endpointParameterTable()
publicResponseSchemas()

$wrapperDescs
$genericDescs
$fieldEnums
$fieldExamples
$modelDefs
$requestDefs
$paramDescs
$pathParamDescs
$endpointParams

N/A

File: Backend-Admin-PHP/app/Support/ApiDocEnhancer.php
Package: Application
Class hierarchy: \App\Support\ApiDocEnhancer
Implements
Uses

Constants

ERROR_RESPONSES

ERROR_RESPONSES = [400 => '响应-参数错误', 401 => '响应-未认证', 403 => '响应-无权限', 404 => '响应-资源不存在', 429 => '响应-限流', 500 => '响应-服务端错误']

错误状态码 → 复用响应组件名。

PUBLIC_PATHS

PUBLIC_PATHS = ['/captcha/image', '/site', '/login', '/register/send-code', '/register/verify-code', '/register/complete', '/forgot-password', '/reset-password', '/reset-password/verify-token', '/templates/{code}/render']

无需认证的公开接口路径，与 routes/api/* 无认证中间件的接口保持一致。

Properties

$

$ : \App\Support\注解仅作代码注释，文档渲染以本注册表为准。

handle()

handle(\Dedoc\Scramble\Support\Generator\OpenApi  $document, \Dedoc\Scramble\OpenApiContext  $context) : void

转换入口：按「文档级 → 包装层 → Schema 层 → 参数层」顺序装配文档。

流程：① 懒加载全部注册表 ② 首页总览与 Bearer 认证 ③ 注册标准错误响应组件 ④ 补全模型 Schema ⑤ 整理响应包装与分页结构 ⑥ 注入 Schema 层描述 ⑦ 整理查询/路径参数 ⑧ 内联请求体描述 ⑨ 补全 store 必填字段。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi	$document
\Dedoc\Scramble\OpenApiContext	$context

loadRegistries()

loadRegistries() : void

applyInfoOverview()

applyInfoOverview(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

文档首页总览：写入项目 API 约定（响应包装/状态码/认证/权限/限流/分组）。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

configureSecurity()

configureSecurity(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

认证方案：全局 Bearer + 公开接口清单豁免。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

registerErrorResponses()

registerErrorResponses(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

注册标准错误响应组件，并按接口类型挂载引用。

公开接口挂 400/429/500；受保护接口挂 400/401/403/429/500，含路径参数（模型绑定）的接口追加 404。422 由 Scramble 的 ValidationException 组件承载，不重复注入。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

attachErrorResponses()

attachErrorResponses(\Dedoc\Scramble\Support\Generator\Operation  $operation, \Dedoc\Scramble\Support\Generator\OpenApi  $document, bool  $isPublic, string  $pathKey) : void

为单个操作挂载标准错误响应引用；同码响应以后挂载者为准。

Parameters

\Dedoc\Scramble\Support\Generator\Operation	$operation
\Dedoc\Scramble\Support\Generator\OpenApi	$document
bool	$isPublic
string	$pathKey

describeSuccessResponses()

describeSuccessResponses(\Dedoc\Scramble\Support\Generator\Operation  $operation) : void

成功响应补默认描述；仅填空，保留 Scramble 生成的有意义描述。

Parameters

\Dedoc\Scramble\Support\Generator\Operation

$operation

buildErrorResponse()

buildErrorResponse(int  $code) : \Dedoc\Scramble\Support\Generator\Response

构造统一包装的错误响应组件：{ code, message, data }。

Parameters

int

$code

Returns

\Dedoc\Scramble\Support\Generator\Response —

patchResponseEnvelopes()

patchResponseEnvelopes(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

整理全部接口的 2xx 响应包装： ① code/message/data 只在包装层注入描述，杜绝串位到业务字段； ② 分页 data.list 修正为模型数组引用、meta 分页字段修正为 integer； ③ 列表/树形接口的 data 数组 items 指向对应模型 Schema。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

patchEnvelope()

patchEnvelope(\Dedoc\Scramble\Support\Generator\Types\ObjectType  $type, \Dedoc\Scramble\Support\Generator\OpenApi  $document, ?string  $schemaName, string  $path) : void

单接口响应包装整理。只处理顶层 { code, message, data } 结构。

Parameters

\Dedoc\Scramble\Support\Generator\Types\ObjectType	$type
\Dedoc\Scramble\Support\Generator\OpenApi	$document
?string	$schemaName
string	$path

patchSpecialResponses()

patchSpecialResponses(\Dedoc\Scramble\Support\Generator\Types\ObjectType  $type, \Dedoc\Scramble\Support\Generator\OpenApi  $document, string  $path) : void

固定形状的特判响应：用户信息、目录分区、地区统计等 Scramble 无法推断的结构。

Parameters

\Dedoc\Scramble\Support\Generator\Types\ObjectType	$type
\Dedoc\Scramble\Support\Generator\OpenApi	$document
string	$path

jobStatusCountItems()

jobStatusCountItems(string  $keyField, string  $keyDesc) : \Dedoc\Scramble\Support\Generator\Types\ObjectType

队列按状态计数的行结构：type_code/date + status_0..status_4。

Parameters

string	$keyField
string	$keyDesc

Returns

\Dedoc\Scramble\Support\Generator\Types\ObjectType —

describeSkippedItems()

describeSkippedItems(mixed  $items) : void

导入/批量操作的 skipped 行描述：兼容 Scramble 的 anyOf 双分支推断。

Parameters

mixed

$items

ensureModelSchemas()

ensureModelSchemas(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

模型 Schema 补全：注册表定义的模型 Schema 一律注册进 components，已存在的（Scramble 生成的）同步描述/枚举/示例并清除响应视角多余的 required。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

buildModelType()

buildModelType(array  $def, string  $schemaName, \Dedoc\Scramble\Support\Generator\Components  $components) : \Dedoc\Scramble\Support\Generator\Types\ObjectType

由模型定义构造 ObjectType（仅用于 Scramble 未生成的模型），与同步路径一致地注入枚举与示例。

Parameters

array	$def
string	$schemaName
\Dedoc\Scramble\Support\Generator\Components	$components

Returns

\Dedoc\Scramble\Support\Generator\Types\ObjectType —

synchronizeModelSchema()

synchronizeModelSchema(\Dedoc\Scramble\Support\Generator\Types\ObjectType  $type, array  $def, string  $schemaName, \Dedoc\Scramble\Support\Generator\Components  $components) : void

同步已存在的模型 Schema：覆盖描述、注入枚举/示例、重建数组 items、清除 required。

Parameters

\Dedoc\Scramble\Support\Generator\Types\ObjectType	$type
array	$def
string	$schemaName
\Dedoc\Scramble\Support\Generator\Components	$components

buildType()

buildType(array  $spec, \Dedoc\Scramble\Support\Generator\Components  $components) : \Dedoc\Scramble\Support\Generator\Types\Type

字段规格 → Type 实例。

Parameters

array	$spec
\Dedoc\Scramble\Support\Generator\Components	$components

Returns

\Dedoc\Scramble\Support\Generator\Types\Type —

buildItemsType()

buildItemsType(array  $items, \Dedoc\Scramble\Support\Generator\Components  $components) : \Dedoc\Scramble\Support\Generator\Types\Type

数组 items 规格 → Type 实例，支持字符串/对象/模型引用三种形态。

Parameters

array	$items
\Dedoc\Scramble\Support\Generator\Components	$components

Returns

\Dedoc\Scramble\Support\Generator\Types\Type —

buildObjectItemsType()

buildObjectItemsType(array  $fields, \Dedoc\Scramble\Support\Generator\Components  $components) : \Dedoc\Scramble\Support\Generator\Types\ObjectType

items 内嵌对象规格 → ObjectType。

Parameters

array	$fields
\Dedoc\Scramble\Support\Generator\Components	$components

Returns

\Dedoc\Scramble\Support\Generator\Types\ObjectType —

enhanceComponentSchemas()

enhanceComponentSchemas(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

组件 Schema 层描述注入：模型走同步、请求走注册表、其余仅补通用描述。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

applyRequestSchema()

applyRequestSchema(\Dedoc\Scramble\Support\Generator\Types\ObjectType  $type, string  $schemaName) : void

请求 Schema 整理：类级描述收敛为一行，字段按注册表覆盖描述并注入枚举/示例。覆盖而非填空——Scramble 会把 rules 行注释当作字段描述带进文档，须以注册表为准。

Parameters

\Dedoc\Scramble\Support\Generator\Types\ObjectType	$type
string	$schemaName

applyFieldSemantics()

applyFieldSemantics(mixed  $type, string  $schemaName, string  $fieldPath, bool  $override = false) : void

递归注入字段语义：描述（注册表 > 通用表 > 保留原值）、枚举、示例。

Parameters

mixed	$type
string	$schemaName	所属 Schema 名，空表示无 Schema 上下文
string	$fieldPath	字段路径，如 positions.*.x
bool	$override	Schema 级注册表描述是否覆盖既有描述

descFor()

descFor(string  $schemaName, string  $path) : ?string

字段描述查找：Schema 级注册表 > 通用描述表。

Parameters

string	$schemaName
string	$path

Returns

?string —

enumFor()

enumFor(string  $key, string  $field) : ?array

枚举查找：Schema 级 > 通用表。

Parameters

string	$key
string	$field

Returns

?array —

exampleFor()

exampleFor(string  $key, string  $field) : mixed

示例查找：Schema 级 > 通用表。

Parameters

string	$key
string	$field

Returns

mixed —

applyEnum()

applyEnum(\Dedoc\Scramble\Support\Generator\Types\Type  $type, ?array  $enum) : void

枚举注入：写入 enum 与 x-enumDescriptions，界面展示取值下拉与取值含义。布尔字段的枚举键转为 true/false 以匹配字段类型。

Parameters

\Dedoc\Scramble\Support\Generator\Types\Type	$type
?array	$enum

applyExample()

applyExample(\Dedoc\Scramble\Support\Generator\Types\Type  $type, mixed  $example) : void

示例注入：示例表无值时跳过。

Parameters

\Dedoc\Scramble\Support\Generator\Types\Type	$type
mixed	$example

enhanceInlineRequestBodies()

enhanceInlineRequestBodies(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

内联请求体（无命名 Request 类的接口）：按虚拟 Schema 名注入注册表描述。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

ensureConfigSaveRequestBody()

ensureConfigSaveRequestBody(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

为裸 Request 的 PUT /admin/configs 创建请求体文档。

ConfigController::save 用裸 Request（动态配置键值对，无 FormRequest 类）， Scramble 无法推断 requestBody → 文档缺 body；此处按 full-replace 语义构造 { key: value, tabs?: {...} } 结构（additionalProperties 描述动态键）。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

enhanceParameters()

enhanceParameters(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

参数整理：按端点参数表补缺、补描述；路径参数强制中文；注入枚举与示例。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

enhanceSingleParameter()

enhanceSingleParameter(\Dedoc\Scramble\Support\Generator\Parameter  $param, string  $pathKey) : void

单参数整理：路径参数强制中文描述，查询参数补描述并注入枚举/示例。

Parameters

\Dedoc\Scramble\Support\Generator\Parameter	$param
string	$pathKey

fixStoreRequiredFields()

fixStoreRequiredFields(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

修正 store 方法的 required 字段。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document

resolveInlineSchemaName()

resolveInlineSchemaName(string  $path, string  $method) : string

从 API 路径反推虚拟 Schema 名，用于内联请求体匹配注册表。

Parameters

string	$path
string	$method

Returns

string —

overviewMarkdown()

overviewMarkdown() : string

文档首页总览：统一响应、状态码、认证、权限、限流、分组约定。

Returns

string —

wrapperDescriptions()

wrapperDescriptions() : array

响应包装层字段描述，只在包装层注入，避免与业务字段串位。

Returns

array —

genericDescriptions()

genericDescriptions() : array

通用字段描述，仅在字段自身无描述时填充。

Returns

array —

fieldEnums()

fieldEnums() : array

枚举表：Schema 级键（如模型-系统菜单.type）优先于通用字段名。值与含义写入 x-enumDescriptions，界面以下拉展示取值与含义。

Returns

array —

fieldExamples()

fieldExamples() : array

示例表：Schema 级键（如请求-登录.username）优先于通用字段名。

Returns

array —

modelSchemaDefinitions()

modelSchemaDefinitions() : array

模型 Schema 定义：字段 → { type, desc, nullable, format, items }。类型取值 int/string/bool/number/object/array；items 取 ['string'] / ['int'] / ['ref', Schema名] / ['object', [字段规格...]]。

Returns

array —

requestSchemaDescriptions()

requestSchemaDescriptions() : array

请求 Schema 描述：desc 为 Schema 级一行描述，fields 为字段描述。

Returns

array —

parameterDescriptions()

parameterDescriptions() : array

查询参数描述：路径前缀键（如 /admin/menus:type）优先于通用名。

Returns

array —

pathParameterDescriptions()

pathParameterDescriptions() : array

路径参数中文描述：覆盖 Scramble 的英文默认描述。

Returns

array —

endpointParameterTable()

endpointParameterTable() : array

端点查询参数表：GET 端点 → { 参数名: 描述 }，用于补全 Scramble 缺失的参数。

Returns

array —

publicResponseSchemas()

publicResponseSchemas(\Dedoc\Scramble\Support\Generator\OpenApi  $document) : void

公开接口的固定形状响应 Schema：站点信息 / 验证码。

供 patchEnvelope 以引用挂到对应接口，保证形状与描述稳定。

Parameters

\Dedoc\Scramble\Support\Generator\OpenApi

$document