How can I provide query parameter example values?

[alexwaibel]

Ask a question
When using the @api.doc() decorator, how can I provide an example request value?

Additional context
The documentation for @api.doc() is rather incomplete at the moment but I've been able to piece together the following request decorator:

@api.doc(params={'someparam: {'description': 'A param description', 'in': 'query', 'type': 'string', 'required': 'true'}})

The above works as expected passing all of the information to swagger. However, the following does not pass the example value to Swagger:

@api.doc(params={'someparam: {'description': 'A param description', 'in': 'query', 'type': 'string', 'required': 'true', 'example': 'example_value'}})

Is there some way to pass this example value along that I'm missing?

Somewhat related, though not the subject of the question; I've also noticed the following works to add a description to a route:

@api.doc(description='Some text describing the route')

However, the following does not work:

@api.doc(summary='Some text describing the route')

I had initially assumed these decorators were simply being parsed and passed directly into Swagger but that does not appear to be the case. I'm also open to other better ways to achieve this if any exist as the above decorators have grown quite large.

[jblom]

@alexwaibel you can use the default param to provide an example, e.g.

@api.doc(params={
	'someparam1': {'in': 'query', 'description': 'Param 1 is for...', 'default': 'Example of param 1'},
	'someparam2': {'in': 'query', 'description': 'Param 2 is for...', 'default': 'Example of param 2'}
},

[alexwaibel]

@jblom my concern is that using default indicates something different than an example. I have some query parameters that are not optional and have no default value so providing an example value for such parameters and having it labelled as the "default" would be misleading to those consuming the generated documentation.

[jblom]

@alexwaibel ok I see. In the @api.expect(someDataModel) for defining the payload model, I noticed it is possible to distinguish example & default:

someDataModel = api.model('grlc-request', {
	'endpoint': fields.String(
		description='SPARQL endpoint',
		required=True,
		default='BENG-LD',
		example='BENG-LD')
})

I just checked and (for @api.doc()) you could simply use the description parameter for the example (and leave out the default). It is not perfect, but might be good enough for your needs.

It seems the UI will render the description as an example (see user, the repo param has a default defined):