php - php swagger注释json属性中方括号的转义字符

Question

我在 Php Laravel 中编写 API 并使用 swagger (2.0) 注释（lib: darkaonline/l5-swagger使用swagger-php）来生成 swagger.json，但是我有以下问题 - 当我输入时：

/**
 *
 * Space Schema
 *
 * @SWG\Get(
 *     path="/api/v1/client/space/schema",
 *     @SWG\Response( 
 *        response=200, 
 *        description="OK",
 *        @SWG\Property(property="result", type="json", example={ "aa": [ "bb", "cc" ] }  )
 *      )
 * )

并尝试生成 swagger.json 我得到：

[Syntax Error] Expected PlainValue, got '[' in ...

但是当我不使用方括号时，例如：

@SWG\Property(property="result", type="json", example={ "ee": "ff" })

然后一切都很好。但是我需要使用方括号，所以问题是：

[swagger注释中json字符串中（方括号）的转义字符是什么？

我还想补充一点，我的示例 json 很大很复杂

Answer 1

我无意中找到了更好的解决方案：

更改方括号（[和]）：

@SWG\Property(property="result", type="json", example={ "aa": [ "bb", "cc" ] }  )

到大括号（{和}）：

@SWG\Property(property="result", type="json", example={ "aa": { "bb", "cc" } }  )

如您所见，我们使用大括号，但是我们不使用 key:value conwention（仅键），因此 swagger 能够检测数组。

而且我们在 swagger-ui 中有漂亮且易于格式化的 json :)

Answer 2

我发现了一些不是 100% 令人满意的解决方法，但是我将它放在这里：

改变

@SWG\Property(property="result", type="json", example={ "aa": [ "bb", "cc" ] }  )

至：

@SWG\Property(property="result", type="json", example="{ ""aa"": [ ""bb"", ""cc"" ] }" )

您可以使用此正则表达式来转换 json 中的引号。

如果您有问题，您也可以更改type="json"为

type="string", format="json"

但是要非常小心，因为您更改了 API 结果定义...

此解决方案的缺点是，在swagger-ui中，您将不会得到格式良好的 json，而是双倍的字符串，""但是如果您单击“模型”，那么您的复制将消失，开发人员将能够复制示例 json