swag icon indicating copy to clipboard operation
swag copied to clipboard

Improve operation param parsing

Open pi-kei opened this issue 9 months ago • 0 comments

Is your feature request related to a problem? Please describe.

Operation comment @Param description does not allow double quotes inside. And there's no way to escape double quotes. Example

// @Param example_param query string false "You can use " inside description"

Produces

{
 "type": "string",
 "description": "You can use ",
 "name": "example_param",
 "in": "query"
},

Operation comment @Param attribute enums() does not allow comma inside a value. And there's no way to escape comma. Example

// @Param example_param2 query string false "Test description" enums(1,2 , 3,4 , 5,6)

Produces

{
 "enum": [
  "1",
  "2",
  "3",
  "4",
  "5",
  "6"
 ],
 "type": "string",
 "description": "Test description",
 "name": "example_param2",
 "in": "query"
}

There may be more things like that.

Describe the solution you'd like

I want to be able to use double quotes inside description with a way to escape double quote. I want to be able to use comma inside enums attribute with a way to escape comma inside value. One of the way to escape these symbols is by using backslash in front of it. Another way to escape these symbols is by doubling it, but backslash looks more explicit and less confusing.

Describe alternatives you've considered

I've tried to avoid using double quotes in description by using html entity " but it does not work when I need to wrap something with double quotes inside backticks:

// @Param example_param query string false "You can use `"` inside description"

This will leave " as is which is not what I want.

Comma in enums values is mandatory because it will pass this values to an actual request when I click Try it out -> Execute in swagger-ui and I can't pass somethig different.

Additional context

I can make a PR to resolve this. But first I want a feedback on this.

pi-kei avatar May 04 '24 19:05 pi-kei