Scramble项目中BodyParameter示例参数的正确用法

在Laravel API文档生成工具Scramble的使用过程中，开发者可能会遇到关于BodyParameter注解中示例参数配置的问题。本文将详细介绍如何正确使用example和examples参数，帮助开发者避免常见错误。

问题背景

当开发者尝试为数组类型的请求体参数定义多个示例值时，可能会自然地想到使用examples参数并传入一个数组，如：

#[BodyParameter(name: 'payment_methods', type: 'array', examples: ['payment1', 'payment2'])]

然而，这种用法会导致系统报错，因为Scramble对examples参数有特定的格式要求。

正确用法解析

Scramble实际上区分了两种不同的示例参数：

1. 简单示例(example)：用于提供参数的基本示例值

   #[BodyParameter(name: 'payment_methods', type: 'array', example: ['payment1', 'payment2'])]
   

2. 详细示例(examples)：当需要为示例提供额外说明时使用，需要传入Example实例

   use Dedoc\Scramble\Support\Generator\Example;
   
   #[BodyParameter(
       name: 'payment_methods', 
       type: 'array', 
       examples: [
           new Example('示例1', ['payment1', 'payment2']),
           new Example('示例2', ['payment3', 'payment4']),
       ]
   )]
   

技术原理

Scramble的这种设计源于OpenAPI规范对示例的不同处理方式。简单示例(example)直接展示值，而复杂示例(examples)则允许为每个示例添加描述性文本，这在API文档中能提供更丰富的上下文信息。

最佳实践建议

1. 对于大多数简单场景，使用example参数即可满足需求
2. 当API参数可能有多种典型使用场景时，考虑使用examples配合Example类
3. 数组类型的参数示例应该保持示例值与参数类型一致
4. 对于复杂嵌套结构，确保示例完整展示数据结构

通过理解这些细微差别，开发者可以更有效地利用Scramble生成清晰、有用的API文档，提升API的可用性和开发者体验。