Swag: How to declare example for string param?

[henrahmagix]

Is your feature request related to a problem? Please describe.
I have a required string parameter, but I don't know how to add an example value for it in declarative comments:

// @Router /hello/{name} [get]
// @Param name path string true "The name to say hello to"

produces

/hello/{name}:
  get:
    parameters:
    - description: The name to say hello to
      in: path
      name: name
      required: true
      type: string

Describe the solution you'd like
Perhaps an attribute at the end?

// @Param name path string true "The name to say hello to" example(Henry)

Describe alternatives you've considered
An example declaration tied to a param name:

// @Param name path string true "The name to say hello to"
// @Example name "Henry"

Additional context
I'm generating the definitions with github.com/swaggo/swag/cmd/swag v1.6.1 using swag init, and https://github.com/apiaryio/dredd to test the definitions against the real thing. Dredd requires an example value (though I may be using Dredd wrong and instead should use its hooks – but I really like the idea of everything coming from swag declarative comments).

If I use default(Henry) then Dredd works but it prints a warning. Ideally I'd like to be able to set example definitions via comments.

warn: API description URI template expansion warning in /api/swagger.yaml (Hello Test > /hello/{name} > Says hello to name with title > 200): Required URI parameter 'name' has a default value.
Default value for a required parameter doesn't make sense from API description perspective. Use example value instead.

[henrahmagix]

Turns out Dredd uses x-example: instead of example: in the parameters definition.

Is it possible to pass custom key/values to the parameter definition in declarative comments? I'd like to generate from the comments but that would override any custom additions to the yaml file like x-example: Henry

[ubogdan]

@easonlin404 i think the best way is to add another atribute named "extensions" and we whould be able to define what ever we need.
Example

// @Param string query string false "string valid" minlength(5) maxlength(10) extensions(x-nullable,x-abc=def)

Note: this will work only for primitives.

[easonlin404]

I agree. Only thing I concerns is swag already have example tag for structs, but for parameters with query, path, we have to to use a different declared way to use that would get little bit confused.

[ubogdan]

any suggestions ?

[arturovm]

Hello! At Credijusto we're using swag to generate our API specs, and we need this feature precisely. Would it be alright for me to adopt this issue? How can we reach consensus about the best way to go about implementing this?

Cheers!

[mullerch]

It would also be great to have a way to define the example for the response body through '@ Success'.

[arvenil]

Generated swagger documentation can't be tried out because there is no way to provide example for param. What worked for me is default(1234) but then this generates "Default value: 1234" text which is misleading. From UI perspective it looks pretty straightforward to have example(1234) but that doesn't work.