Clarify GET /allocations/$c for nonexistent $c

There was a note in the API reference for "List allocations" indicating
the response payload when a nonexistent consumer is queried, but the
parameter table entry for `consumer_generation` was duplicated from the
"Manage" and "Update" operations, which was confusing.

This commit clarifies that the `consumer_generation` will be entirely
absent from the response payload in this scenario. It also adds the same
clarification for the `project_id` and `user_id` fields. And tightens up
the gabbi coverage proving same.

Change-Id: I70f22b246d0c0acd1ae87a75bc438a9258b704ad
Story: #2006726
Task: #37146

api-ref/source/allocations.inc

@@ -97,7 +97,7 @@ Response
   - allocations: allocations_by_resource_provider
   - generation: resource_provider_generation
   - resources: resources
-  - consumer_generation: consumer_generation_min
+  - consumer_generation: consumer_generation_get
   - project_id: project_id_body_1_12
   - user_id: user_id_body_1_12
 

api-ref/source/parameters.yaml

@@ -480,6 +480,12 @@ consumer_generation: &consumer_generation
   description: >
     The generation of the consumer. Should be set to ``null`` when indicating
     that the caller expects the consumer does not yet exist.
+consumer_generation_get:
+  <<: *consumer_generation
+  description: >
+    The generation of the consumer. Will be absent when listing allocations for
+    a consumer uuid that has no allocations.
+  min_version: 1.28
 consumer_generation_min:
   <<: *consumer_generation
   min_version: 1.28
@@ -529,6 +535,9 @@ project_id_body: &project_id_body
   in: body
 project_id_body_1_12:
   <<: *project_id_body
+  description: >
+    The uuid of a project. Will be absent when listing allocations for
+    a consumer uuid that has no allocations.
   min_version: 1.12
 project_id_body_1_8:
   <<: *project_id_body
@@ -769,6 +778,9 @@ user_id_body: &user_id_body
   required: true
 user_id_body_1_12:
   <<: *user_id_body
+  description: >
+    The uuid of a user. Will be absent when listing allocations for
+    a consumer uuid that has no allocations.
   min_version: 1.12
 user_id_body_1_8:
   <<: *user_id_body

placement/tests/functional/gabbits/allocations-1.28.yaml

@@ -24,6 +24,22 @@ defaults:
 
 tests:
 
+- name: old version get nonexistent
+  GET: /allocations/11111111-1111-1111-1111-111111111111
+  request_headers:
+      openstack-api-version: placement 1.27
+  response_json_paths:
+      # This is the entire response. There is no generation or proj/user id.
+      $:
+        allocations: {}
+
+- name: new version get nonexistent
+  GET: /allocations/22222222-2222-2222-2222-222222222222
+  response_json_paths:
+      # This is the entire response. There is no generation or proj/user id.
+      $:
+        allocations: {}
+
 - name: old version no gen no existing
   PUT: /allocations/11111111-1111-1111-1111-111111111111
   request_headers:
@@ -180,11 +196,23 @@ tests:
       consumer_generation: $HISTORY["new version serialization contains consumer generation"].$RESPONSE["consumer_generation"]
   status: 204
 
-- name: should now return no allocations for this consumer
+- name: old version should now return no allocations for this consumer
+  GET: /allocations/44444444-4444-4444-4444-444444444444
+  request_headers:
+      openstack-api-version: placement 1.27
+  status: 200
+  response_json_paths:
+      # This is the entire response. There is no generation or proj/user id.
+      $:
+        allocations: {}
+
+- name: new version should now return no allocations for this consumer
   GET: /allocations/44444444-4444-4444-4444-444444444444
   status: 200
   response_json_paths:
-      $.allocations.`len`: 0
+      # This is the entire response. There is no generation or proj/user id.
+      $:
+        allocations: {}
 
 # The following tests cover cases where we are putting allocations to
 # multiple resource providers from one consumer uuid, both a brand new