All parameters are described as "template" in api-ref.html output since 1.9.0 clouddocs-maven-plugin

[Anne Gentle]

When 1.9.0 was released, the output for api-ref.html added two columns to the parameter descriptions -- one is supposed to be the parameter style and the other the type from the XSD-defined namespace. However the parameter style is always "template" which has a special meaning for some OpenStack APIs.

[Tom Fifield (fifieldt)]

I'm also seeing 'header' and 'query'.

Can you clarify what parameter style is supposed to be?

[David Cramer (david-thingbag)]

Template parameters are the parts of the url that are replaced, like {tenant_id}.
Query params are the part of the url after the ? like baz in http://foo/bar?baz=10.
Header params are params passed in the http header.
There are also matrix parameters, but I don't understand those yet.

http://www.w3.org/Submission/wadl/#x3-270011

[Anne Gentle (annegentle)]

In the context of WADL, those definitions are fine. For the context of output from WADL, we need to use another term than template. Is there a way to do that?

[David Cramer (david-thingbag)]

Yes, we can present it however we like.

Btw., I forgot to mention plain parameters (style="plain"). Those are used to indicate what should be in the request body.

I think Diane has a proposal for this and I have an item in my backlog for it.

Plain params should be a separate table. Maybe each kind of param should be a separate table?

What terms should we use for each kind of param?

query params => query params (I think that's standard)
header params => header params (seems clear enough)
plain params => Maybe don't call them params...just have a table for "Request Body" or whatever.
template params => ????

[Diane Fleming (diane-fleming)]

query params => query parameters
header params => header parameters
plain params => Request body attributes
template params =>URI parameters

I've added a file - sample_outputs.xml - that shows suggested sample tables.

 https://review.openstack.org/43729

[Diane Fleming (diane-fleming)]

I added sample outputs to the bk_example.xml file - second to last chapter.

[Anne Gentle (annegentle)]

Diane's looks good - thanks for the explanation too!

[Diane Fleming (diane-fleming)]

David, I'll open an issue against clouddocs-mvn-plugin -

change "template" parameters to URI parameters.

[David Cramer (david-thingbag)]

Fixed in 1.11.1-SNAPSHOT. We should have a release soon.