Escape character for sqare brackets in php swagger annotation json property

Question

I write API in Php Laravel and use swagger (2.0) annotations (lib: darkaonline/l5-swagger which use swagger-php ) to generate swagger.json, however I have following problem - when I type:

/**
 *
 * 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" ] }  )
 *      )
 * )

And try to gen swagger.json I get:

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

But when I not use square brackets like for example:

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

Then everything is fine. However I need to use square brackets so the question is:

What is escape character for [ (square bracket) in json string in swagger annotations?

I also wanna add that my example json is quite big and complicated

Answer 1

I accidentally found better solution:

Change square brackets ( [ and ] ) in:

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

to braces ( { and } ):

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

As you can see, we use braces, however we not use key:value conwention (only keys) so swagger is able to detect array.

And we have nice and easy formatted json in swagger-ui :)

Answer 2

I found some workaround which is not 100% satisfying however I will put it here:

Change

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

to:

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

You can use this regexp to convert quotes in your json.

If you have some problem you can also change type="json" to

type="string", format="json"

hovewer be very carrefull with that because you change API result definition...

The drawback of this solution is that in swagger-ui You will not get nice formatted json but string with doubled "" however if you click on "Model" then you duplication will dissapear and developer will be able to copy example json