[api-ref]Orchestration create stack post body incorrectly documented

[Steven Hardy]

http://developer.openstack.org/api-ref-orchestration-v1.html#stacks

The POST body arguments are incorrectly titled "Response parameters" which could be confusing to users.

[Anne Gentle (annegentle)]

Steve, is it for POST/v1/​{tenant_id}​/stacks only?

[Qiming Teng (tengqim)]

Anne, there are other inaccuracies as well. Will report bugs and propose fixes later on.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/146020

[Steven Hardy (shardy)]

Anne, I think it's only POST/v1/​{tenant_id}​/stacks which has the "Response parameters" error.

I'm sure there are other innacuracies too, as mentioned by Qiming, but we can report those independently, the scope of this bug is just fixing the POST for create.

[OpenStack Infra (hudson-openstack)]

Change abandoned by Qiming Teng (<email address hidden>) on branch: master
Review: https://review.openstack.org/146020
Reason: this is frustrating, won't do it this way.

[Atsushi SAKAI (sakaia)]

From seeing #1 and #2, it needs a description which argument has problem.
Also Currently no patch is submitted yet.

[Steven Hardy (shardy)]

> From seeing #1 and #2, it needs a description which argument has problem.

I already provided that in comment #4, it's all of the "Response parameters" fields, which aren't responses at all, but really part of the POST body, e.g part of the request.

http://developer.openstack.org/api-ref-orchestration-v1.html#stack_create

> Also Currently no patch is submitted yet.

That is not a reason to mark a bug incomplete :\

[Steven Hardy (shardy)]

So, looking at the patch (which has been submitted, many months ago):

https://review.openstack.org/#/c/146020/

The reason this is stalled, is because of problems with clouddocs-maven-plugin, Anne and Qiming had a discussion in the review which resulted in the determination that there weren't resources right now to fix clouddocs-maven-plugin.

So, either this remains open and we wait for that to change, someone steps up to fix clouddocs-maven-plugin, or we look again at the implementation and look for a workaround to the issues discussed there.

Or, this could be closed wont fix I guess, which would be disappointing given that this presumably is a common issue for all POST body documentation (otherwise there'd be a pattern we could look at and reuse to solve the problem).