Update api-ref documentation

Adds message id, expires_at, created_at parameters to user messages in
response body.

Updates share_types response body to account for extra_specs object including
snapshot_support, create_from_snapshot_support, mount_snapshot_support,
revert_to_snapshot_support, replication_type, and
driver_handles_share_servers.

Change-Id: I408dcf5fdbf2f12eb1dc0ce80232d4e710cef765

api-ref/source/parameters.yaml

@@ -1076,7 +1076,39 @@ extra_spec_key:
   type: string
 extra_specs:
   description: |
-    The extra specifications for the share type.
+    Extra specifications of the share type. These are key=value pairs of
+    capabilities that the shares of this type are expected to possess.
+    For more information, see `Share Types
+    <https://docs.openstack.org/manila/latest/admin/shared-
+    file-systems-share-types.html>`_.
+    Some examples include:
+    ``driver_handles_share_servers``,
+    ``replication_type``,
+    ``snapshot_support``,
+    ``mount_snapshot_support``,
+    ``revert_to_snapshot_support``,
+    ``create_share_from_snapshot_support``
+  in: body
+  required: true
+  type: object
+extra_specs_request_body:
+  description: |
+    Extra specifications of the share type. These are key=value pairs of
+    capabilities that the shares of this type are expected to possess.
+    For more information, see `Share Types
+    <https://docs.openstack.org/manila/latest/admin/shared-
+    file-systems-share-types.html>`_. When creating a new share type, required
+    extra-specifications **must** be provided.
+    ``driver_handles_share_servers`` is a required extra-specification,
+    and ``snapshot_support`` was considered a required extra-specification
+    until API version 2.24. When updating extra-specs of a share type,
+    there's no need to provide required extra specifications unless they need
+    to be updated. Some examples of extra-specifications include:
+    ``replication_type``,
+    ``snapshot_support``,
+    ``mount_snapshot_support``,
+    ``revert_to_snapshot_support``,
+    ``create_share_from_snapshot_support``
   in: body
   required: true
   type: object
@@ -1425,6 +1457,31 @@ maxTotalSnapshotGigabytesOptional:
   in: body
   required: false
   type: integer
+message_expires_at_body:
+  description: |
+    The date and time stamp when the resource message will expire within the
+    service's database.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    The ``±hh:mm`` value, if included, returns the time zone as an
+    offset from UTC.
+
+    For example, ``2016-12-31T13:14:15-05:00``.
+  in: body
+  required: true
+  type: string
+message_id_body:
+  description: |
+    The UUID of the message.
+  in: body
+  required: true
+  type: string
 message_level_body:
   in: body
   required: true
@@ -2059,7 +2116,9 @@ requested_capabilities:
 required_extra_specs:
   description: |
     The required extra specifications for the share
-    type.
+    type: ``driver_handles_share_servers``. ``snapshot_support`` was
+    treated as a required extra-specification until 
+    api version 2.24.
   in: body
   required: true
   type: object

api-ref/source/share-types.inc

@@ -122,13 +122,7 @@ Response parameters
    - name: share_type_name
    - required_extra_specs: required_extra_specs
    - extra_specs: extra_specs
-   - driver_handles_share_servers: driver_handles_share_servers
-   - replication_type: replication_type
-   - snapshot_support: snapshot_support
-   - mount_snapshot_support: mount_snapshot_support
-   - revert_to_snapshot_support: revert_to_snapshot_support
-   - share_type_access:is_public: share_type_access:is_public
-   - create_share_from_snapshot_support: create_share_from_snapshot_support
+   - share_type_access:is_public: share_type_access:is_public_body
    - description: share_type_description
    - is_default: is_default_type
 
@@ -175,9 +169,7 @@ Response parameters
    - id: share_type_id_body
    - required_extra_specs: required_extra_specs
    - extra_specs: extra_specs
-   - driver_handles_share_servers: driver_handles_share_servers
-   - snapshot_support: snapshot_support
-   - share_type_access:is_public: share_type_access:is_public
+   - share_type_access:is_public: share_type_access:is_public_body
    - name: share_type_name
    - description: share_type_description
    - is_default: is_default_type
@@ -226,13 +218,7 @@ Response Parameters
    - id: share_type_id_body
    - required_extra_specs: required_extra_specs
    - extra_specs: extra_specs
-   - driver_handles_share_servers: driver_handles_share_servers
-   - snapshot_support: snapshot_support
-   - replication_type: replication_type
-   - mount_snapshot_support: mount_snapshot_support
-   - revert_to_snapshot_support: revert_to_snapshot_support
-   - create_share_from_snapshot_support: create_share_from_snapshot_support
-   - share_type_access:is_public: share_type_access:is_public
+   - share_type_access:is_public: share_type_access:is_public_body
    - name: share_type_name
    - description: share_type_description
    - is_default: is_default_type
@@ -279,12 +265,6 @@ Response parameters
 .. rest_parameters:: parameters.yaml
 
    - extra_specs: extra_specs
-   - driver_handles_share_servers: driver_handles_share_servers
-   - snapshot_support: snapshot_support
-   - replication_type: replication_type
-   - mount_snapshot_support: mount_snapshot_support
-   - revert_to_snapshot_support: revert_to_snapshot_support
-   - create_share_from_snapshot_support: create_share_from_snapshot_support
 
 Response example
 ----------------
@@ -322,15 +302,9 @@ Request
 
 
    - project_id: project_id_path
-   - extra_specs: extra_specs
-   - driver_handles_share_servers: driver_handles_share_servers
-   - snapshot_support: snapshot_support
+   - extra_specs: extra_specs_request_body
    - os-share-type-access:is_public: os-share-type-access:is_public
-   - name: share_type_name_request
-   - replication_type: replication_type
-   - mount_snapshot_support: mount_snapshot_support
-   - revert_to_snapshot_support: revert_to_snapshot_support
-   - create_share_from_snapshot_support: create_share_from_snapshot_support
+   - name: share_type_name
    - description: share_type_description_request
 
 Request example
@@ -347,15 +321,9 @@ Response parameters
    - id: share_type_id_body
    - required_extra_specs: required_extra_specs
    - extra_specs: extra_specs
-   - driver_handles_share_servers: driver_handles_share_servers
-   - snapshot_support: snapshot_support
    - os-share-type-access:is_public: os-share-type-access:is_public
    - share_type_access:is_public: share_type_access:is_public
    - name: share_type_name
-   - replication_type: replication_type
-   - mount_snapshot_support: mount_snapshot_support
-   - revert_to_snapshot_support: revert_to_snapshot_support
-   - create_share_from_snapshot_support: create_share_from_snapshot_support
    - description: share_type_description
    - is_default: is_default_type
 
@@ -446,7 +414,7 @@ Request
 
    - project_id: project_id_path
    - share_type_id: share_type_id
-   - extra_specs: extra_specs
+   - extra_specs: extra_specs_request_body
 
 Request example
 ---------------
@@ -662,14 +630,8 @@ Response parameters
    - id: share_type_id_body
    - required_extra_specs: required_extra_specs
    - extra_specs: extra_specs
-   - driver_handles_share_servers: driver_handles_share_servers
-   - snapshot_support: snapshot_support
    - share_type_access:is_public: share_type_access:is_public_body
    - name: share_type_name
-   - replication_type: replication_type
-   - mount_snapshot_support: mount_snapshot_support_body
-   - revert_to_snapshot_support: revert_to_snapshot_support_body
-   - create_share_from_snapshot_support: create_share_from_snapshot_support_body
    - description: share_type_description_body
    - is_default: is_default_type_body
 

api-ref/source/user-messages.inc

@@ -63,6 +63,7 @@ Response parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - id: message_id_body
    - action_id: action_id_body
    - detail_id: detail_id_body
    - message_level: message_level_body
@@ -71,6 +72,8 @@ Response parameters
    - resource_id: resource_id_body
    - resource_type: resource_type_body
    - message_members_links: message_members_links
+   - expires_at : message_expires_at_body
+   - created_at : created_at
 
 
 Response example
@@ -116,6 +119,7 @@ Response parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - id: message_id_body
    - action_id: action_id_body
    - detail_id: detail_id_body
    - message_level: message_level_body
@@ -124,6 +128,8 @@ Response parameters
    - resource_id: resource_id_body
    - resource_type: resource_type_body
    - message_links: message_links
+   - expires_at : message_expires_at_body
+   - created_at : created_at
 
 
 Response example