[doc][api-ref] Fix annotation and missing parameters

- Call out the maximum API version in Stein (2.49) - Add parameter 'cast_rules_to_readonly' to share instance API ref - Remove parameters 'export_location' and 'export_locations' from share instance API ref. - Add "min_version" and "max_version" annotations on parameters where missing. - Add "versionadded" annotation to APIs - Add "DEPRECATED" annotation to deprecated APIs along with a warning message. Identical changes to the manage/unmanage APIs are handled in https://review.openstack.org/#/c/647973/ Partial-Bug: #1760644 Change-Id: I5342cc26d1cbeea8ca3d55868e0f69d525333421
2019-03-26 20:14:42 -07:00 · 2019-03-26 20:14:42 -07:00 · 41d243c394
parent 5cd643785d
commit 41d243c394
19 changed files with 168 additions and 38 deletions
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@ -415,6 +415,7 @@ share_type_query:
  in: query
  required: false
  type: string
+  min_version: 2.23
 share_types_query:
  description: |
    A list of one or more share type IDs. Allows filtering share groups.
@ -2832,6 +2833,14 @@ share_id_2:
  in: body
  required: true
  type: string
+share_instance_cast_rules_to_readonly:
+  description: |
+    If the share instance has its ``cast_rules_to_readonly`` attribute set to
+    True, all existing access rules will be cast to read/only.
+  in: body
+  required: true
+  type: string
+  min_version: 2.30
 share_instance_id_1:
  description: |
    The UUID of the share instance.
@ -2991,11 +3000,12 @@ share_replica_az:
  type: string
 share_replica_cast_rules_to_readonly:
  description: |
-    Since the share instance has its ``cast_rules_to_readonly`` attribute
-    set to True, existing rules will be cast to read/only.
+    If the share replica has its ``cast_rules_to_readonly`` attribute set to
+    True, all existing access rules will be cast to read/only.
  in: body
  required: true
  type: string
+  min_version: 2.30
 share_replica_created_at:
  description: |
    The date and time stamp when the share replica was created.
--- a/api-ref/source/quota-sets.inc
+++ b/api-ref/source/quota-sets.inc
@ -130,11 +130,13 @@ Response example
   :language: javascript


-Show quota set in detail
-========================
+Show quota set in detail (since API v2.25)
+==========================================

 .. rest_method::  GET /v2/{tenant_id}/quota-sets/{tenant_id}/detail?user_id={user_id}

+.. versionadded:: 2.25
+
 Shows quotas for a tenant in detail.

 If you specify the optional ``user_id`` query parameter, you get
--- a/api-ref/source/samples/share-instances-list-response.json
+++ b/api-ref/source/samples/share-instances-list-response.json
@ -6,11 +6,8 @@
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:41:20.000000",
-            "export_location": "10.254.0.3:/shares/share-081f7030-c54f-42f5-98ee-93a37393e0f2",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
-            "export_locations": [
-                "10.254.0.3:/shares/share-081f7030-c54f-42f5-98ee-93a37393e0f2"
-            ],
+            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "id": "081f7030-c54f-42f5-98ee-93a37393e0f2"
@ -21,11 +18,8 @@
            "availability_zone": "nova",
            "replica_state": null,
            "created_at": "2015-09-07T08:51:34.000000",
-            "export_location": "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b",
            "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
-            "export_locations": [
-                "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b"
-            ],
+            "cast_rules_to_readonly": false,
            "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
            "host": "manila2@generic1#GENERIC1",
            "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"
--- a/api-ref/source/samples/share-show-instance-response.json
+++ b/api-ref/source/samples/share-show-instance-response.json
@ -5,11 +5,8 @@
        "availability_zone": "nova",
        "replica_state": null,
        "created_at": "2015-09-07T08:51:34.000000",
-        "export_location": "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b",
+        "cast_rules_to_readonly": false,
        "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
-        "export_locations": [
-            "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b"
-        ],
        "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
        "host": "manila2@generic1#GENERIC1",
        "access_rules_status": "active",
--- a/api-ref/source/share-access-rule-metadata.inc
+++ b/api-ref/source/share-access-rule-metadata.inc
@ -1,7 +1,7 @@
 .. -*- rst -*-

 ============================================
-Share access rule metadata (Since API v2.45)
+Share access rule metadata (since API v2.45)
 ============================================

 Updates, and unsets share access rule metadata.
@ -11,6 +11,8 @@ Update share access rule metadata

 .. rest_method::  PUT /v2/{tenant_id}/share-access-rules/{access_id}/metadata

+.. versionadded:: 2.45
+
 Updates the metadata for a share access rule.

 Response codes
@ -61,6 +63,8 @@ Unset share access rule metadata

 .. rest_method::  DELETE /v2/{tenant_id}/share-access-rules/{access_id}/metadata/{key}

+.. versionadded:: 2.45
+
 Un-sets the metadata on a share access rule.

 To unset a metadata key value, specify only the key name in the
--- a/api-ref/source/share-access-rules.inc
+++ b/api-ref/source/share-access-rules.inc
@ -3,7 +3,7 @@
 .. _get-access-rules-after-2-45:

 ====================================
-Share access rules (Since API v2.45)
+Share access rules (since API v2.45)
 ====================================

 Retrieve details about access rules
@ -13,6 +13,7 @@ Describe share access rule

 .. rest_method::  GET /v2/{tenant_id}/share-access-rules/{access_id}

+.. versionadded:: 2.45

 Retrieve details about a specified access rule.

@ -66,6 +67,8 @@ List share access rules

 .. rest_method::  GET /v2/{tenant_id}/share-access-rules?share_id={share-id}

+.. versionadded:: 2.45
+
 Lists the share access rules on a share.

 .. note::
--- a/api-ref/source/share-actions.inc
+++ b/api-ref/source/share-actions.inc
@ -170,18 +170,21 @@ Request example
   :language: javascript


-List access rules (versions 1.0 to 2.44)
-========================================
+List access rules (DEPRECATED)
+==============================
+
+.. warning::
+
+   This API is deprecated starting with microversion 2.45 and requests to
+   this API will fail with a 404 starting from microversion 2.45. Use
+   :ref:`List share access rules <get-access-rules-after-2-45>` API
+   instead of this API from version 2.45.

 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action

 Lists access rules for a share. The Access ID returned is necessary to deny
 access.

-.. note::
-  Use :ref:`List share access rules <get-access-rules-after-2-45>` API
-  instead of this API from version 2.45
-
 Response codes
 --------------

@ -452,13 +455,15 @@ Response parameters
 There is no body content for the response.


-Revert share to snapshot
-========================
+Revert share to snapshot (since API v2.27)
+==========================================

 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action

+.. versionadded:: 2.27
+
 Reverts a share to the specified snapshot, which must be the most recent one
-known to manila. This API is available in versions later than or equal to 2.27.
+known to manila.

 Response codes
 --------------
--- a/api-ref/source/share-export-locations.inc
+++ b/api-ref/source/share-export-locations.inc
@ -17,6 +17,8 @@ List export locations

 .. rest_method::  GET /v2/{tenant_id}/shares/{share_id}/export_locations

+.. versionadded:: 2.9
+
 Lists all export locations for a share.

 Response codes
@ -64,6 +66,8 @@ Show single export location

 .. rest_method::  GET /v2/{tenant_id}/shares/{share_id}/export_locations/{export_location_id}

+.. versionadded:: 2.9
+
 Show details of an export location belonging to a share.

 Response codes
--- a/api-ref/source/share-group-snapshots.inc
+++ b/api-ref/source/share-group-snapshots.inc
@ -27,6 +27,8 @@ List share group snapshots

 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots

+.. versionadded:: 2.31
+
 Lists all share group snapshots.

 Response codes
@ -79,6 +81,8 @@ List share group snapshots with details

 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/detail

+.. versionadded:: 2.31
+
 Lists all share group snapshots with details.

 Response codes
@ -137,6 +141,8 @@ List share group snapshots members

 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/members

+.. versionadded:: 2.31
+
 Lists all share group snapshots members.

 Response codes
@ -186,6 +192,8 @@ Show share group snapshot details

 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}

+.. versionadded:: 2.31
+
 Shows details for a share group snapshot.

 Response codes
@ -236,6 +244,8 @@ Create share group snapshot

 .. rest_method::  POST /v2/{tenant_id}/share-group-snapshots

+.. versionadded:: 2.31
+
 Creates a snapshot from a share.

 Response codes
@ -296,6 +306,8 @@ Reset share group snapshot state

 .. rest_method::  POST /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/action

+.. versionadded:: 2.31
+
 Administrator only. Explicitly updates the state of a share group snapshot.

 Use the ``policy.json`` file to grant permissions for this action
@ -336,6 +348,8 @@ Update share group snapshot

 .. rest_method::  PUT /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}

+.. versionadded:: 2.31
+
 Updates a share group snapshot.

 Response codes
@ -396,6 +410,8 @@ Delete share group snapshot

 .. rest_method::  DELETE /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}

+.. versionadded:: 2.31
+
 Deletes a share group snapshot.

 Response codes
--- a/api-ref/source/share-group-types.inc
+++ b/api-ref/source/share-group-types.inc
@ -39,6 +39,8 @@ List share group types

 .. rest_method::  GET /v2/{tenant_id}/share-group-types

+.. versionadded:: 2.31
+
 Lists all share group types.

 Response codes
@ -79,6 +81,8 @@ List default share group types

 .. rest_method::  GET /v2/{tenant_id}/share-group-types/default

+.. versionadded:: 2.31
+
 Lists default share group types.

 Response codes
@ -126,6 +130,8 @@ List share group types extra specs

 .. rest_method::  GET /v2/{tenant_id}/share-group-types/{share_group_type_id}/group_specs

+.. versionadded:: 2.31
+
 Lists the extra specifications for a share group type.

 Response codes
@ -169,6 +175,8 @@ Create share group type

 .. rest_method::  POST /v2/{tenant_id}/share-group-types

+.. versionadded:: 2.31
+
 Creates a share group type.

 Response codes
@ -227,6 +235,8 @@ Show share group type access details

 .. rest_method::  GET /v2/{tenant_id}/share-group-types/{share_group_type_id}/share_type_access

+.. versionadded:: 2.31
+
 Shows access details for a share group type.

 You can view access details for private share group types only.
@ -273,6 +283,8 @@ Set extra spec for share group type

 .. rest_method::  POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/group_specs

+.. versionadded:: 2.31
+
 Sets an extra specification for the share group type.

 Response codes
@ -324,6 +336,8 @@ Unset an group spec

 .. rest_method::  DELETE /v2/{tenant_id}/share-group-types/{share_group_type_id}/group-specs/{group_spec_key}

+.. versionadded:: 2.31
+
 Unsets an extra specification for the share type.

 Response codes
@ -355,6 +369,8 @@ Add share group type access

 .. rest_method::  POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/action

+.. versionadded:: 2.31
+
 Adds share group type access for a project.

 You can add access to private share group types only.
@ -395,6 +411,8 @@ Remove share group type access

 .. rest_method::  POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/action

+.. versionadded:: 2.31
+
 Removes share group type access from a project.

 You can remove access from private share group types only.
@ -434,6 +452,8 @@ Delete share group type

 .. rest_method::  DELETE /v2/{tenant_id}/share-group-types/{share_group_type_id}

+.. versionadded:: 2.31
+
 Deletes a share group type.

 Response codes
--- a/api-ref/source/share-groups.inc
+++ b/api-ref/source/share-groups.inc
@ -28,6 +28,8 @@ List share groups

 .. rest_method::  GET /v2/{tenant_id}/share_groups

+.. versionadded:: 2.31
+
 Lists all share groups.

 Response codes
@ -89,6 +91,8 @@ Show share group details

 .. rest_method::  GET /v2/{tenant_id}/share_groups/{share_group_id}

+.. versionadded:: 2.31
+
 Shows details for a share group.


@ -146,6 +150,8 @@ Create share group

 .. rest_method::  POST /v2/{tenant_id}/share_groups

+.. versionadded:: 2.31
+
 Creates a share group.

 Response codes
@ -216,6 +222,8 @@ Reset share group state

 .. rest_method::  POST /v2/{tenant_id}/share-groups/{share_group_id}/action

+.. versionadded:: 2.31
+
 Administrator only. Explicitly updates the state of a share group.

 Use the ``policy.json`` file to grant permissions for this action
@ -257,6 +265,8 @@ Update share group

 .. rest_method::  PUT /v2/{tenant_id}/share-groups/{share_group_id}

+.. versionadded:: 2.31
+
 Updates a share group.

 Response codes
@ -322,6 +332,8 @@ Delete share group

 .. rest_method::  DELETE /v2/{tenant_id}/share-groups/{share_group_id}

+.. versionadded:: 2.31
+
 Deletes a share group.

 Response codes
--- a/api-ref/source/share-instance-export-locations.inc
+++ b/api-ref/source/share-instance-export-locations.inc
@ -19,6 +19,8 @@ List export locations

 .. rest_method::  GET /v2/{tenant_id}/share_instances/{share_instance_id}/export_locations

+.. versionadded:: 2.9
+
 Response codes
 --------------

@ -64,6 +66,7 @@ Show single export location

 .. rest_method::  GET /v2/{tenant_id}/share_instances/{share_instance_id}/export_locations/{export_location_id}

+.. versionadded:: 2.9

 Response codes
 --------------
--- a/api-ref/source/share-instances.inc
+++ b/api-ref/source/share-instances.inc
@ -14,6 +14,8 @@ List share instances

 .. rest_method::  GET /v2/{tenant_id}/share_instances

+.. versionadded:: 2.3
+
 Lists all share instances.

 Response codes
@ -51,6 +53,7 @@ Response parameters
   - replica_state: replica_state
   - export_location: export_location
   - export_locations: export_locations
+   - cast_rules_to_readonly: share_instance_cast_rules_to_readonly
   - share_network_id: share_network_id_4
   - share_server_id: share_server_id
   - host: host_6
@ -68,6 +71,8 @@ Show share instance details

 .. rest_method::  GET /v2/{tenant_id}/share_instances/{share_instance_id}

+.. versionadded:: 2.3
+
 Shows details for a share instance.

 Response codes
@ -105,6 +110,7 @@ Response parameters
   - replica_state: replica_state
   - export_location: export_location
   - export_locations: export_locations
+   - cast_rules_to_readonly: share_instance_cast_rules_to_readonly
   - share_network_id: share_network_id_4
   - share_server_id: share_server_id
   - host: host_6
@ -122,6 +128,8 @@ Reset share instance state

 .. rest_method::  POST /v2/{tenant_id}/share_instances/{share_instance_id}/action

+.. versionadded:: 2.3
+
 Administrator only. Explicitly updates the state of a share instance.

 Use the ``policy.json`` file to grant permissions for this action
@ -162,6 +170,8 @@ Force-delete share instance

 .. rest_method::  POST /v2/{tenant_id}/share_instances/{share_instance_id}/action

+.. versionadded:: 2.3
+
 Administrator only. Force-deletes a share instance.

 Use the ``policy.json`` file to grant permissions for this action
--- a/api-ref/source/share-migration.inc
+++ b/api-ref/source/share-migration.inc
@ -1,7 +1,7 @@
 .. -*- rst -*-

 ================================
-Share Migration (Since API v2.5)
+Share Migration (since API v2.5)
 ================================
 As an administrator, you can migrate a share with its data from one
 location to another in a manner that is transparent to users and workloads.
@ -20,11 +20,19 @@ Possible use cases for data migration include:
    #experimental-apis>`_ .


-Migrate share (versions 2.5 to 2.14)
-=========================================
+Migrate share (DEPRECATED)
+==========================
+
+.. warning::
+
+   This API is deprecated starting with microversion 2.15 and requests to
+   this API will fail with a 404 starting from microversion 2.15. Please see
+   the new experimental API below.

 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action

+.. versionadded:: 2.5
+
 Migrates a share from one back end to another.

 You can migrate a share from one back end to another but both back
@ -61,11 +69,13 @@ Request
   - force_host_copy: force_host_copy


-Start Migration (Since version 2.15)
-====================================
+Start Migration (since API v2.15)
+=================================

 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action

+.. versionadded:: 2.15
+
 Initiates share migration. This API will initiate the share data copy to the
 new host. The copy operation is non-disruptive.

@ -97,11 +107,13 @@ Request
   - force_host_copy: force_host_copy


-Complete Migration (Since version 2.15)
+Complete Migration (since API v2.15)
 =======================================

 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action

+.. versionadded:: 2.15
+
 Completes share migration. This API will initiate the switch-over from the
 source to destination share. This operation is disruptive.

--- a/api-ref/source/share-replica-export-locations.inc
+++ b/api-ref/source/share-replica-export-locations.inc
@ -13,6 +13,8 @@ List export locations

 .. rest_method::  GET /v2/{tenant_id}/share-replicas/{share_replica_id}/export-locations

+.. versionadded:: 2.47
+
 Response codes
 --------------

@ -60,6 +62,8 @@ Show single export location

 .. rest_method::  GET /v2/{tenant_id}/share-replicas/{share_replica_id}/export-locations/{export-location-id}

+.. versionadded:: 2.47
+

 Response codes
 --------------
--- a/api-ref/source/share-replicas.inc
+++ b/api-ref/source/share-replicas.inc
@ -1,8 +1,8 @@
 .. -*- rst -*-

-===================================
-Share replicas (Since version 2.11)
-===================================
+================================
+Share replicas (since API v2.11)
+================================

 Share replicas are the replicated copies of the existing share. You can use
 Share Replicas to sync data so that each share replica has an identical copy
@ -57,6 +57,8 @@ Create share replica

 .. rest_method::  POST /v2/{tenant_id}/share-replicas

+.. versionadded:: 2.11
+
 Create a share replica for the share.

 Response codes
@ -118,6 +120,8 @@ Promote share replica

 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action

+.. versionadded:: 2.11
+
 Promotes a replica to ``active`` replica state.

 Response codes
@ -148,6 +152,8 @@ Resync share replica

 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action

+.. versionadded:: 2.11
+
 Resync a replica with its ``active`` mirror.

 Response codes
@ -178,6 +184,8 @@ List share replicas

 .. rest_method::  GET /v2/{tenant_id}/share-replicas?share_id={share_id}

+.. versionadded:: 2.11
+
 Lists share replicas.

 Response codes
@ -224,6 +232,8 @@ List share replicas with details

 .. rest_method::  GET /v2/{tenant_id}/share-replicas/detail?share_id={share_id}

+.. versionadded:: 2.11
+
 Lists share replicas with details.

 Response codes
@ -276,6 +286,8 @@ Show share replica

 .. rest_method::  GET /v2/{tenant_id}/share-replicas/{share_replica_id}

+.. versionadded:: 2.11
+
 Show a share replica.

 Response codes
@ -329,6 +341,8 @@ Reset status of the share replica

 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action

+.. versionadded:: 2.11
+
 Administrator only. Explicitly updates the ``status`` of a share replica.

 Use the ``policy.json`` file to grant permissions for this action
@ -370,6 +384,8 @@ Reset replica_state of the share replica

 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action

+.. versionadded:: 2.11
+
 Administrator only. Explicitly updates the ``replica state`` of a share replica.

 Use the ``policy.json`` file to grant permissions for this action
@ -411,6 +427,8 @@ Delete share replica

 .. rest_method::  DELETE /v2/{tenant_id}/share-replicas/{share_replica_id}

+.. versionadded:: 2.11
+
 Deletes a share replica.

 Response codes
@ -446,6 +464,8 @@ Force-delete share replica

 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action

+.. versionadded:: 2.11
+
 Administrator only. Force-deletes a share replica in any state.

 Use the ``policy.json`` file to grant permissions for this action
--- a/api-ref/source/snapshot-instances.inc
+++ b/api-ref/source/snapshot-instances.inc
@ -21,6 +21,8 @@ List share snapshot instances

 .. rest_method::  GET /v2/{tenant_id}/snapshot-instances

+.. versionadded:: 2.19
+
 Lists all share snapshot instances.

 Response codes
@ -65,6 +67,8 @@ List share snapshot instances with details

 .. rest_method::  GET /v2/{tenant_id}/snapshot-instances/detail

+.. versionadded:: 2.19
+
 Lists all share snapshot instances with details.

 Response codes
@ -115,6 +119,8 @@ Show share snapshot instance details

 .. rest_method::  GET /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id}

+.. versionadded:: 2.19
+
 Shows details for a share snapshot instance.

 Response codes
@ -166,6 +172,8 @@ Reset share snapshot instance state

 .. rest_method::  POST /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id}/action

+.. versionadded:: 2.19
+
 Administrator only. Explicitly updates the state of a share snapshot instance.

 Use the ``policy.json`` file to grant permissions for this action
--- a/api-ref/source/user-messages.inc
+++ b/api-ref/source/user-messages.inc
@ -22,6 +22,8 @@ List user messages

 .. rest_method::  GET /v2/{tenant_id}/messages

+.. versionadded:: 2.37
+
 Lists all user messages.


@ -83,6 +85,8 @@ Show user message details

 .. rest_method::  GET /v2/{tenant_id}/messages/{message_id}

+.. versionadded:: 2.37
+
 Shows details for a user message.

 Response codes
@ -134,6 +138,8 @@ Delete message

 .. rest_method::  DELETE /v2/{tenant_id}/messages/{message_id}

+.. versionadded:: 2.37
+
 Deletes a user message.

 Response codes
--- a/manila/api/openstack/rest_api_version_history.rst
+++ b/manila/api/openstack/rest_api_version_history.rst
@ -271,7 +271,7 @@ user documentation.
  only within specific availability zones. The extra-spec allows using
  comma separated names of one or more availability zones.

-2.49
----
+2.49 (Maximum in Stein)
+-----------------------
  Added Manage/Unmanage Share Server APIs. Updated Manage/Unmanage Shares and
  Snapshots APIs to work in ``driver_handles_shares_servers`` enabled mode.