swaggo / swag

Automatically generate RESTful API documentation with Swagger 2.0 for Go.
MIT License
10.24k stars 1.17k forks source link

Improve operation param parsing #1805

Open pi-kei opened 2 months ago

pi-kei commented 2 months ago

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.