api-ref: GET /v3/auth/tokens doesn't mention the optional "system" parameter for a scoped token

[Matt Riedemann]

This came about from a discussion in IRC:

http://eavesdrop.openstack.org/irclogs/%23openstack-dev/%23openstack-dev.2018-05-30.log.html#t2018-05-30T16:13:41

The API reference here doesn't mention that for a system-scoped token, the response body can have a 'system' attribute in the 'token' object in the response body:

https://developer.openstack.org/api-ref/identity/v3/index.html#validate-and-show-information-for-token

The example in the API reference is for an unscoped token, but for SDK writers the API reference should have a description of all the possible response parameters and indicate if they are optional, and the description can explain in what cases they would be present in the response.

For example, GET /servers/{id} can have a "fault" parameter in the response but only under certain scenarios based on the server status:

https://developer.openstack.org/api-ref/compute/#show-server-details

But we still document the optional parameter.

[Lance Bragstad (lbragstad)]

After looking at these docs and the addition of another scope target in Queens, it wouldn't be a bad idea to make the examples more explicit.

Instead of listing various scopes as option in a generic response, we can make things more clear by generating explicit requests and responses for each type.

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/571309
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=75da4da4761d70dca00fda042e284dcbf54d3627
Submitter: Zuul
Branch: master

commit 75da4da4761d70dca00fda042e284dcbf54d3627
Author: Lance Bragstad <email address hidden>
Date: Mon Jun 4 20:49:14 2018 +0000

    Clarify scope responses in authentication api ref

    The documentation was a bit misleading because it listed projects,
    domains, and the system as not being optional. This is confusing
    because it's not possible to scope a token to more than one target.

    This commit attempts to clarify those details.

    Closes-Bug: 1774229
    Change-Id: I27fb15e2b53529b91c0f2bd3a2744d60b54495c8

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/keystone 14.0.0.0rc1 release candidate.