Bug 1409753

Summary: API documentation confusing
Product: Red Hat OpenStack Reporter: Aleksandar Kostadinov <akostadi>
Component: documentationAssignee: RHOS Documentation Team <rhos-docs>
Status: CLOSED NOTABUG QA Contact: RHOS Documentation Team <rhos-docs>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: unspecifiedCC: dcadzow, mburns, srevivo
Target Milestone: ---Keywords: Reopened
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
URL: http://developer.openstack.org/api-ref/compute/?expanded=create-server-detail
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2019-01-24 22:05:47 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Aleksandar Kostadinov 2017-01-03 09:03:10 UTC 
Description of problem:
Hello, OpenStack API documentation is confusing for me as a user and causes wastes much more time than reasonable when I try to use it.

For example http://developer.openstack.org/api-ref/compute/?expanded=create-server-detail

There is no indication I can see about API call structure. From the table representation I see `server object` with no link to actual server object structure. Then I see for example `networks` parameter. From table it looks like being specified as a standalone param but in fact it needs to be specified under `server`. There is one exmple which shows where `networks` is to be set, but there is no example about `block_device_mapping_v2`.

I think that for a reasonable user experience, the tables describing call parameters in documentation need to show the proper structure of those params.

As an example I'd provide the OpenShift API [1] where each `object` has a link to its structure instead of a flat parameter list in the request table. You can see how table links to `v1.BuildConfig` and then the table for `v1.BuildConfig` links to other structures.

[1] https://docs.openshift.com/container-platform/latest/rest_api/openshift_v1.html#create-a-buildconfig
Comment 1 Lucy Bopf 2017-06-23 05:30:42 UTC 
Bugs against upstream documentation can be reported here:
https://bugs.launchpad.net/nova/+filebug
Comment 2 Aleksandar Kostadinov 2017-06-23 09:48:27 UTC 
https://access.redhat.com/solutions/2680301 

It seems like we don't maintain an API documentation. I think we should do that, as well fix issues inside it as the one described above.
Comment 3 Derek 2019-01-24 22:05:47 UTC 
Please report the issue to the link provided above in comment 1.  The Red Hat documentation group does not work on the upstream docs.  Closing this bug.