如何在l5-swagger中指定additionalProperties编写OpenAPI文档

核心问题定位 #

你之前的写法存在两个和OpenAPI规范不匹配的地方，导致生成的文档结构完全不符合实际返回：

• 错把active_options的对象结构当成数组处理：@OA\Items注解仅适用于type="array"的列表类返回，对应JSON结构为[]包裹的顺序元素集合，无法用来描述{}包裹的键值对对象。
• 认知偏差：OpenAPI规范中根本没有optionalProperties这个内置参数，定义“无固定命名、任意可选键组合的对象”是通过原生的additionalProperties规则实现的，完全不需要手动枚举所有可能出现的键名。

标准实现方法 #

OpenAPI v3 针对“对象键名不固定、但所有键对应的返回值结构统一”的场景，提供了additionalProperties规则支持：只要在属性定义中声明该属性是type="object"，再通过嵌套的@OA\AdditionalProperties注解定义所有动态键对应的值结构，即可完美匹配你描述的“任意数字键组合、每个键值为带name/type的对象”的返回逻辑。

可直接复用的完整注解代码 #

*   @OA\Response(
*     response=200,
*     description="Settings",
*     @OA\JsonContent(
*       // active_options 动态键对象定义
*       @OA\Property(
*         property="active_options",
*         type="object",
*         description="已激活的配置选项，键为选项ID，任意键组合均为合法返回",
*         // 核心规则：定义所有动态键对应的统一值结构
*         @OA\AdditionalProperties(
*           type="object",
*           @OA\Property(property="name", type="string", description="选项名称"),
*           @OA\Property(property="type", type="string", description="选项类型")
*         )
*       ),
*       // server 固定结构对象定义
*       @OA\Property(
*         property="server",
*         type="object",
*         @OA\Property(property="url", type="string", description="服务访问地址"),
*         @OA\Property(property="settings1", type="string", description="自定义服务配置项")
*       ),
*       // message 字符串提示
*       @OA\Property(property="message", type="string", description="接口返回提示")
*     )
*   ),

效果说明 #

上述注解生成的接口文档示例会完全匹配你提供的实际返回结构：

• active_options会被识别为对象结构，不会错误生成数组格式
• 文档会明确说明该对象内部支持任意字符串/数字作为键名，每个键对应的值必须包含name和type两个字符串类型字段
• 不需要手动枚举"1""2""3"这类具体键名，文档完全符合键可选、任意组合的业务逻辑

常见注意事项 #

• 如果需要限制动态键的命名规则（比如仅允许数字字符串作为键），可以在active_options属性下额外搭配@OA\PatternProperties注解做正则匹配限制，绝大多数业务场景下仅用additionalProperties就足够满足需求
• 注意版本兼容：如果使用的swagger-php版本低于v3，需要将@OA\AdditionalProperties替换为属性内直接传值的写法，目前主流的l5-swagger发行版本均已支持嵌套注解的写法
• 结构区分逻辑：如果返回的集合元素本身没有独立业务键、仅为顺序排列的列表，再使用type="array"搭配@OA\Items定义；如果集合的每个元素需要通过独立键名（比如选项ID）索引，就用对象+additionalProperties的结构定义。

内容的提问来源于stack exchange，提问作者badluck