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

Question

我在PhpLaravel中写API并使用swagger(2.0)注解(lib:darkaonline/l5-swagger which use 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

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

改变

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

至：

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

您可以使用 this regexp 转换 json 中的引号。

如果你有什么问题你也可以把type="json"改成

type="string", format="json"

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

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

Answer 2

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

更改方括号（[ 和 ]）在：

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

到大括号（{ 和 }）：

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

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

而且我们在 swagger-ui 中已经很好地格式化了 json :)

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

Escape character for sqare brackets in php swagger annotation json property

php

json

annotations

swagger-2.0

swagger-php

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

Escape character for sqare brackets in php swagger annotation json property

php

json

annotations

swagger-2.0

swagger-php

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