PHPSwaggerGen

PHPSwaggerGen copied to clipboard

At the moment the following code will collapse everything into one line. It makes the description harder to read once rendered in Swagger UI, and prevent using Markdown syntax to format things like lists.

 * @rest\description Useful endpoint that does 2 things:
 * - this
 * - and that

Actual result:

"description":"Useful endpoint that does 2 things: - this - and that"

Expected result:

"description":"Useful endpoint that does 2 things:\n - this\n - and that"

Is there any way to preserve the end of line?

I can't change the default behaviour due to backwards compatibility, but perhaps an option could be added to change this. Something like an enableLinebreaks() or such. Alternatively, perhaps we can come up with a way to specify this in the @rest\description syntax itself. Are there any precedents for such kind of behaviour in other frameworks?

I don't know. It's tricky because sometimes you might want to break the lines just to have a more readable source code (e.g. you want to limit the lines to 80 characters) while sometimes you want the line break to be kept for the Markdown formatting for Swagger UI.

There is somewhat the same problem if you use a YAML file directly: one line break is ignored (same behavior has your lib), you need an additional empty line to count as a line break in Swagger UI (so basically \n\n becomes \n in the end result).