api-ref: cleanup os-server-groups 'policies' parameter description

The 'policies' parameter for the os-server-groups API is an array
for legacy reasons, but the schema validation allows only a single
item and it's from the enumerated list, and exactly one must be
specified when creating a server group.

This patch cleans up the policies parameter description to avoid
confusion over the number of items that can be specified or their
form, and it also provides a description of each available policy.

Since the jsonschema for policies is a bit confusing too, this
patch adds a comment in the schema code to avoid future confusion
over how the validation works.

Change-Id: I3ab2880ed6e8bb2cdf476c197719b83d768d44d0
Closes-Bug: #1652943

api-ref/source/parameters.yaml

@@ -3492,11 +3492,20 @@ personality:
   type: string
 policies:
   description: |
-    A list of one or more policy names to associate with the server group. The list
-    must contain at least one policy name. The current valid policy names are ``anti-affinity``
-    , ``affinity``, ``soft-anti-affinity`` and ``soft-affinity``, the latter two were
-    added in microversion 2.15.  Each policy name must be a non-empty string with
-    no leading or trailing spaces. Maximum length is 255 characters.
+    A list of exactly one policy name to associate with the server group. The
+    current valid policy names are:
+
+    - ``anti-affinity`` - servers in this group must be scheduled to
+      different hosts.
+    - ``affinity`` - servers in this group must be scheduled to the same host.
+    - ``soft-anti-affinity`` - servers in this group should be scheduled to
+      different hosts if possible, but if not possible then they should still
+      be scheduled instead of resulting in a build failure. This policy was
+      added in microversion 2.15.
+    - ``soft-affinity`` - servers in this group should be scheduled to the same
+      host if possible, but if not possible then they should still be scheduled
+      instead of resulting in a build failure. This policy was added in
+      microversion 2.15.
   in: body
   required: true
   type: array

nova/api/openstack/compute/schemas/server_groups.py

@@ -26,6 +26,11 @@ create = {
             'properties': {
                 'name': parameter_types.name,
                 'policies': {
+                    # This allows only a single item and it must be one of the
+                    # enumerated values. So this is really just a single string
+                    # value, but for legacy reasons is an array. We could
+                    # probably change the type from array to string with a
+                    # microversion at some point but it's very low priority.
                     'type': 'array',
                     'items': [{'enum': ['anti-affinity', 'affinity']}],
                     'uniqueItems': True,