api-ref: document encryption type provider choices

This updates the encrypted volume type provider
parameter descriptions for the create and update
requests to note the two choices of 'luks' and 'plain'.
Since we don't want those choices in the response
parameter descriptions, the parameters have to be
broken down a bit in the parameters.yaml file to
be request/response and optional/required.

There are currently other supported values for the
encryption type provider, including the legacy
classpath values, but we want people using the
non-legacy values so only luks and plain are
documented here, and luks is marked as the
recommended choice over plain (dm-crypt).

Change-Id: I496d30ecf6390f51cdd8e547b7345b3da30e92de
Closes-Bug: #1803513

api-ref/source/v3/parameters.yaml

@@ -2145,18 +2145,36 @@ protected:
   required: false
   type: boolean
   min_version: 3.1
-provider:
+provider:  # required response parameter (get/create)
   description: |
     The class that provides encryption support.
   in: body
   required: true
   type: string
-provider_optional:
+provider_optional:  # optional response parameter (update)
   description: |
     The class that provides encryption support.
   in: body
   required: false
   type: string
+provider_req:  # required request parameter (create)
+  description: |
+    The class that provides encryption support. Choices are:
+
+    * luks - relies on Linux Unified Key Setup (recommended)
+    * plain - relies on dm-crypt
+  in: body
+  required: true
+  type: string
+provider_req_optional:  # optional request parameter (update)
+  description: |
+    The class that provides encryption support. Choices are:
+
+    * luks - relies on Linux Unified Key Setup (recommended)
+    * plain - relies on dm-crypt
+  in: body
+  required: false
+  type: string
 qos_association_id:
   description: |
     The Qos association ID.

api-ref/source/v3/volumes-v3-types.inc

@@ -589,7 +589,7 @@ Request
    - volume_type_id: volume_type_id
    - encryption: encryption
    - key_size: key_size
-   - provider: provider
+   - provider: provider_req
    - control_location: control_location
    - cipher: cipher
 
@@ -645,7 +645,7 @@ Request
    - encryption_id: encryption_id
    - encryption: encryption
    - key_size: key_size
-   - provider: provider_optional
+   - provider: provider_req_optional
    - control_location: control_location
    - cipher: cipher