Swagger-php: Multi-line annotation issues

[cviebrock]

I have some annotations that have really long descriptions:

/*
 * @SWG\Definition(
 *   definition="ImageVariants",
 *   description="A key-value list of image variations. The 'original' key should always be present, but other keys ('large', 'small', etc.) may be present as well, depending on the context and object requested.",
 *  ... etc.
 */

My IDE (PHPStorm) tends to try and keep line lengths shorter -- or I do it manually to make things more readable -- so I end up with:

/*
 * @SWG\Definition(
 *   definition="ImageVariants",
 *   description="A key-value list of image variations. 
 *     The 'original' key should always be present, but other keys
 *     ('large', 'small', etc.) may be present as well, 
 *     depending on the context and object requested.",
 *  ... etc.
 */

swagger-php can parse this just fine, but the resulting json includes the asterisks from the docblock:

"ImageVariants": {
    "description": "A key-value list of image variations.\n     *     The 'original' key should always be present, but other keys\n     *     ('large', 'small', etc.) may be present as well,\n     *     depending on the context and object requested.",
}

Is there anyway around this? Some way to make long values readable in the docblocks, but still to generate the "correct" JSON?

[ribeiropaulor]

It's a limitation of Doctrine Annotations. Although, I'm not sure we can call it a limitation.

At present, you should omit the asterisks and use the following sintaxe.

/*
 * @SWG\Definition(
 *   definition="ImageVariants",
 *   description="A key-value list of image variations. 
      The 'original' key should always be present, but other keys
      ('large', 'small', etc.) may be present as well, 
      depending on the context and object requested.",
 *  ... etc.
 */

If the spaces are a problem, you could do like the following.

/*
 * @SWG\Definition(
 *   definition="ImageVariants",
 *   description="A key-value list of image variations. 
The 'original' key should always be present, but other keys
('large', 'small', etc.) may be present as well, 
depending on the context and object requested.",
 *  ... etc.
 */

It's not ideal, but I think it's enough.

[bravo-kernel]

Closing as per correct explanation by Mr. @ribeiropaulor

[cviebrock]

Couldn't the parser just search for something like \n\s+\*\s+ and remove any instances from the resulting JSON?

[mikepsinn]

You could also enable soft line wraps for the file in PHPStorm and use long lines.

[FractalizeR]

There is an ongoing solution to this: https://github.com/doctrine/annotations/pull/75

[oyepez003]

 * @OA\Get(
 *     path="/foo/bar",
 *     summary="The one line summary ...",
 *     description="<div>
            This is the line 1, This is the line 1, This is the line 1,
            This is the line 1, This is the line 1, This is the line 1.
            <br/><br/>
            This is the line 2, This is the line 2, This is the line 2,
            <br/><br/>
            Notice the single quotes in the link attributes: <a target='_blank' href='https://swagger.io/'>Link</a>.
       </div>",
 *     tags={"My Tag"},
 *     ...