v2 of block storage WADL is missing a lot of response params.

[Katherine Cox-Buday]

For reference: https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl

The "Create volume" specification is very helpful and lists response parameters. Other methods -- like "List volumes" -- don't list any of the return parameters.

I am generating an SDK based on the WADL file, so it's paramount that this information be accurate.

[Anne Gentle (annegentle)]

I'm marking Confirmed, but I still want to double-check on how those could be added to the WADL. I'm going to ask around to be sure.

[Katherine Cox-Buday (cox-katherine-e)]

Yeah, I immediately ran into a question: how do you represent arrays?

So far I've found the following:
https://technet.microsoft.com/en-us/library/dn690140(v=vs.111).aspx

The Images WADL attempts to address this:
https://github.com/openstack/api-site/blob/8d8b52872318bdb2eac6dcb06ddbcd78fe67eeee/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl#L147

But that's a bit strange because it incorrectly defines the array as an xsd:string:
https://github.com/openstack/api-site/blob/6e6cfbb89966ceb9dfd0eeda8be11b328743c1ed/api-ref/src/wadls/image-api/src/v2/common.ent#L171

Is the technique outlined by the Microsoft article acceptable, or is there another example I can follow?

[Anne Gentle (annegentle)]

Here's what I got when I started asking around about how to document these with WADL.

There are two possibilities.

1. Document the items in a json schema...and include the json schema in the grammar section. I believe the Image API v2 does this but only for metadata on the images, and as you found items like &imagesParameter; are actually string types defined in common.ent. https://github.com/openstack/api-site/blob/8d8b52872318bdb2eac6dcb06ddbcd78fe67eeee/api-ref/src/wadls/image-api/src/v2/common.ent#L169 (You figured that out, just putting in here for anyone following along in the bug comments.)

2. Use plain parameters to make a statement about the body using json path. (I think https://github.com/jayway/JsonPath)

If you go with 2 you'll need a different plain parameter for each part if the message. So for the Image example above it could be type plain instead of type string.

As to where the description goes, it would be in the request or response of the method under representation.

What I still don't know is how that would be output in our HTML but since you're interested in the WADL itself that's outside of this scope.

Great questions, thanks for digging in.

[Katherine Cox-Buday (cox-katherine-e)]

I took a look at JsonPath. I don't think this is a great fit. It describes how to find the parameter in question (i.e. the structure of the data), but does nothing to describe type information about the parameter.

It looks like option 1 may be more appropriate. The question is what we describe the type in: XML Schema, or JSON Schema? It looks like the Image API is using XML Schema, so we could stay consistent; however JSON Schema would be just fine too.

In terms of generating the documentation, I think it would be wonderful to pull in this information for display in the HTML; however, as you mentioned, that's outside the scope of this discussion.

Thoughts?

[Anne Gentle (annegentle)]

I got more input from another coworker, here's what he said, and good news, he agrees with you. :)

There's two reasons I strongly favor for #1 over #2. First, if you do #2 there's really no way to make sure you've documented it accurately. Also, the current API docs don't display the jsonpath information anyways, so you'll need to make some display changes as well. Check out my comments here for more details.

Additionally, option #1 is more portable and more useful. At least some Swagger tools will take the descriptions from schemas and turn them into documentation, maintaining the proper structure (something that the plain parameters don't do and that the use of jsonpath is an attempt to circumvent but is not
ideal).
---
I definitely would go for json schema as most OpenStack APIs are dropping XML support for new API designs.

[Atsushi SAKAI (sakaia)]

This is for WADL issue. I want to close this ticket.
If it needs to keep, please change the project from api-site to cinder.

[Anne Gentle (annegentle)]

Oh, she did make the needed changes. It was patch https://review.openstack.org/#/c/158348/. Closing this bug.

[Anne Gentle (annegentle)]

She had tracked with 1424458.