Swagger UI 数组字段字符串问题：根源与解决之道

2024-03-23 17:00:36

Swagger UI 数组类型字段生成字符串问题及其解决方法

在 API 开发过程中，我们可能使用 Swagger UI 来生成交互式 API 文档。然而，有时我们会遇到一个问题，即数组类型字段生成字符串，而不是数组。本文将探讨这一问题及其解决方法。

问题

在 Symfony 5.4 中，API 控制器中数组类型字段的注释如下：

@OA\Property(
   property="email",
   type="array",
   @OA\Items(
       type="string"
   ),
)

使用此注释，Swagger UI 将生成类似于 email=test1,test2 的字符串，而不是 email[]=test1&email[]=test2 或 email[0]=test&email[1]=test2。这会导致在 PHP 中获取的 email 变量为字符串，而不是数组。

原因

这个问题的根源在于 Swagger UI 默认使用 CSV（逗号分隔值）格式表示数组。然而，这种格式并不适用于所有语言和框架。例如，PHP 中的数组通常使用方括号表示，如 ['test1', 'test2']。

解决方法

为了解决这个问题，我们可以使用 collectionFormat 属性指定数组的格式。collectionFormat 属性可以取以下值：

csv：逗号分隔值（默认）
ssv：空格分隔值
tsv：制表符分隔值
pipes：竖线分隔值
multi：表单数据编码

不幸的是，collectionFormat=multi 仅适用于 query 或 formData 类型的参数。因此，对于 multipart/form-data 类型的请求体，我们无法使用此格式。

那么，如何配置 API 注释以获取数组而不是字符串呢？

一种方法是使用自定义序列化器。我们可以创建自定义序列化器类，将数组转换为 CSV 格式，并将此序列化器与 Swagger UI 集成。另一种方法是使用第三方库，例如 swagger-php，它提供了对 Swagger 注解的扩展，允许我们指定数组的格式。

需要注意的是，修改 Swagger 注解的默认行为可能会影响其他使用 Swagger 文档的工具。因此，在进行任何更改之前，请务必仔细考虑影响。

结论

通过使用 collectionFormat 属性或第三方库，我们可以配置 Swagger UI 以数组形式生成数组类型字段，而不是字符串。这有助于确保在 PHP 等语言中正确处理数组。

常见问题解答

为什么 Swagger UI 默认使用 CSV 格式表示数组？
- 为了与 OpenAPI 规范保持一致，OpenAPI 规范指定数组的默认格式为 CSV。
为什么 collectionFormat=multi 不适用于 multipart/form-data 请求体？
- 因为 multipart/form-data 请求体使用不同的编码方案，该方案不支持 multi 格式。
使用自定义序列化器有什么优势？
- 使用自定义序列化器提供了更大的灵活性，因为它允许我们根据特定需求定制序列化过程。
使用第三方库的好处是什么？
- 第三方库提供了开箱即用的解决方案，简化了配置过程，并减少了编写自定义代码的需要。
如何选择最佳解决方法？
- 选择最佳解决方法取决于具体要求和项目的复杂性。如果需要高度可定制性，则自定义序列化器可能更合适。如果需要简单便捷的解决方案，则第三方库可能是更好的选择。