openstack/manila
Code Issues Proposed changes

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

Browse Source 
- 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
This commit is contained in:
Goutham Pacha Ravi 2019-03-26 20:14:42 -07:00
parent 5cd643785d
commit 41d243c394
19 changed files with 168 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
api-ref/source/parameters.yaml
View File

@ -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.

6
api-ref/source/quota-sets.inc
View File

@ -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

10
api-ref/source/samples/share-instances-list-response.json
View File

@ -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"

5
api-ref/source/samples/share-show-instance-response.json
View File

@ -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",

6
api-ref/source/share-access-rule-metadata.inc
View File

@ -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

5
api-ref/source/share-access-rules.inc
View File

@ -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::

23
api-ref/source/share-actions.inc
View File

@ -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
--------------

4
api-ref/source/share-export-locations.inc
View File

@ -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

16
api-ref/source/share-group-snapshots.inc
View File

@ -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

20
api-ref/source/share-group-types.inc
View File

@ -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

12
api-ref/source/share-groups.inc
View File

@ -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

3
api-ref/source/share-instance-export-locations.inc
View File

@ -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
--------------

10
api-ref/source/share-instances.inc
View File

@ -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

24
api-ref/source/share-migration.inc
View File

@ -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.

4
api-ref/source/share-replica-export-locations.inc
View File

@ -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
--------------

26
api-ref/source/share-replicas.inc
View File

@ -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

8
api-ref/source/snapshot-instances.inc
View File

@ -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

6
api-ref/source/user-messages.inc
View File

@ -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

4
manila/api/openstack/rest_api_version_history.rst
View File

@ -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.