From 436e7f9982e9d0e29878006f0a84d36c3ede3420 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 25 Apr 2024 21:53:14 +0100 Subject: [PATCH] api: Add descriptions to API schemas Rather than reinventing the wheel, we simply copy those that we already have. This isn't technically sufficient since we're using reStructuredText and OpenAPI insists on Markdown but we'll fix that in a follow-up. Signed-off-by: Stephen Finucane Change-Id: I4ad95085f4960530a259a93dc923ad5fd5677aeb Partially-implements: bp json-schema-validation --- manila/api/schemas/resource_locks.py | 100 +++++++++++++++++++++++--- manila/api/validation/helpers.py | 32 +++++++++ manila/api/validation/parameters.yaml | 1 + tools/check_exec.py | 3 + 4 files changed, 127 insertions(+), 9 deletions(-) create mode 100644 manila/api/validation/helpers.py create mode 120000 manila/api/validation/parameters.yaml diff --git a/manila/api/schemas/resource_locks.py b/manila/api/schemas/resource_locks.py index aec42c6021..498563a0d8 100644 --- a/manila/api/schemas/resource_locks.py +++ b/manila/api/schemas/resource_locks.py @@ -12,6 +12,7 @@ from oslo_config import cfg +from manila.api.validation import helpers from manila.api.validation import parameter_types from manila.api.validation import response_types from manila.common import constants @@ -28,24 +29,37 @@ create_request_body = { 'resource_id': { 'type': 'string', 'format': 'uuid', + 'description': helpers.description( + 'resource_lock_resource_id' + ), }, 'lock_reason': { 'type': ['string', 'null'], 'maxLength': 1023, + 'description': helpers.description( + 'resource_lock_lock_reason_optional' + ), }, 'resource_type': { 'type': ['string', 'null'], 'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES + (None,), 'default': constants.SHARE_RESOURCE_TYPE, + 'description': helpers.description( + 'resource_lock_resource_type' + ), }, 'resource_action': { 'type': ['string', 'null'], 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,), 'default': constants.RESOURCE_ACTION_DELETE, + 'description': helpers.description( + 'resource_lock_resource_action_create_optional' + ), }, }, 'required': ['resource_id'], 'additionalProperties': False, + 'description': helpers.description('resource_lock_object'), }, }, 'required': ['resource_lock'], @@ -61,13 +75,20 @@ update_request_body = { 'resource_action': { 'type': ['string', 'null'], 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,), + 'description': helpers.description( + 'resource_lock_resource_action_optional' + ), }, 'lock_reason': { 'type': ['string', 'null'], 'maxLength': 1023, + 'description': helpers.description( + 'resource_lock_lock_reason_optional' + ), }, }, 'additionalProperties': False, + 'description': helpers.description('resource_lock_object'), }, }, 'required': ['resource_lock'], @@ -77,61 +98,94 @@ update_request_body = { index_request_query = { 'type': 'object', 'properties': { - 'limit': parameter_types.multi_params( - parameter_types.non_negative_integer - ), - 'marker': parameter_types.multi_params({ - 'type': ['string'], + 'limit': parameter_types.multi_params({ + **parameter_types.non_negative_integer, + 'description': helpers.description('limit'), + }), + # NOTE(stephenfin): This is parsed by 'common.get_pagination_params' + # but we ignore it. We may wish to uncomment this when that is no + # longer the case + # 'marker': parameter_types.multi_params({ + # 'type': ['string'], + # }), + 'offset': parameter_types.multi_params({ + **parameter_types.non_negative_integer, + 'description': helpers.description('offset'), }), - 'offset': parameter_types.multi_params( - parameter_types.non_negative_integer - ), 'sort_key': parameter_types.multi_params({ 'type': 'string', 'default': 'created_at', + 'description': helpers.description('sort_key_resource_locks'), }), # TODO(stephenfin): Make this an enum of ['asc', 'desc'] 'sort_dir': parameter_types.multi_params({ 'type': 'string', 'default': 'desc', + 'description': helpers.description('sort_dir'), }), 'with_count': parameter_types.multi_params(parameter_types.boolean), 'created_since': parameter_types.multi_params({ 'type': 'string', 'format': 'date-time', + 'description': helpers.description('created_since_query'), }), 'created_before': parameter_types.multi_params({ 'type': 'string', 'format': 'date-time', + 'description': helpers.description('created_before_query'), }), 'project_id': parameter_types.multi_params({ 'type': ['string', 'null'], 'format': 'uuid', + 'description': helpers.description( + 'resource_lock_project_id_query' + ), }), 'user_id': parameter_types.multi_params({ 'type': ['string', 'null'], 'format': 'uuid', + 'description': helpers.description('resource_lock_user_id_query') }), 'resource_id': parameter_types.multi_params({ 'type': ['string', 'null'], 'format': 'uuid', + 'description': helpers.description( + 'resource_lock_resource_id_query' + ), }), 'resource_action': parameter_types.multi_params({ 'type': ['string', 'null'], 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,), + 'description': helpers.description( + 'resource_lock_resource_action_query' + ), }), 'resource_type': parameter_types.multi_params({ 'type': ['string', 'null'], 'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES + (None,), + 'description': helpers.description( + 'resource_lock_resource_type_query' + ), + }), + 'all_projects': parameter_types.multi_params({ + **parameter_types.boolean, + 'description': helpers.description( + 'resource_lock_all_projects_query' + ), }), - 'all_projects': parameter_types.multi_params(parameter_types.boolean), 'lock_context': parameter_types.multi_params({ 'type': ['string', 'null'], 'maxLength': 10, + 'description': helpers.description( + 'resource_lock_lock_context_query' + ), }), 'lock_reason': parameter_types.multi_params({ 'type': ['string', 'null'], 'maxLength': 1023, + 'description': helpers.description( + 'resource_lock_lock_reason_query' + ), }), }, # TODO(stephenfin): Exclude additional query string parameters in a future @@ -153,43 +207,70 @@ _resource_lock_response = { 'id': { 'type': 'string', 'format': 'uuid', + 'description': helpers.description('resource_lock_id'), }, 'user_id': { 'type': 'string', 'format': 'uuid', + 'description': helpers.description('resource_lock_user_id'), }, 'project_id': { 'type': 'string', 'format': 'uuid', + 'description': helpers.description('resource_lock_project_id'), }, 'lock_context': { 'type': 'string', + 'description': helpers.description('resource_lock_lock_context'), }, 'resource_type': { 'type': 'string', 'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES, + 'description': helpers.description('resource_lock_resource_type'), }, 'resource_id': { 'type': 'string', 'format': 'uuid', + 'description': helpers.description('resource_lock_resource_id'), }, 'resource_action': { 'type': 'string', 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS, + 'description': helpers.description( + 'resource_lock_resource_action' + ), }, 'lock_reason': { 'type': ['string', 'null'], + 'description': helpers.description('resource_lock_lock_reason'), }, 'created_at': { 'type': 'string', 'format': 'date-time', + 'description': helpers.description('created_at'), }, 'updated_at': { 'type': ['string', 'null'], 'format': 'date-time', + 'description': helpers.description('updated_at'), }, 'links': response_types.links, }, + 'description': helpers.description('resource_lock_object'), + 'required': [ + 'id', + 'user_id', + 'project_id', + 'lock_context', + 'resource_type', + 'resource_id', + 'resource_action', + 'lock_reason', + 'created_at', + 'updated_at', + 'links', + ], + 'additionalProperties': False, } create_response_body = { @@ -210,6 +291,7 @@ index_response_body = { }, 'count': { 'type': 'integer', + 'description': helpers.description('count_without_min_version'), }, 'resource_locks_links': response_types.collection_links, }, diff --git a/manila/api/validation/helpers.py b/manila/api/validation/helpers.py new file mode 100644 index 0000000000..e62f897979 --- /dev/null +++ b/manila/api/validation/helpers.py @@ -0,0 +1,32 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import pathlib + +import yaml + +_PARAMETERS_YAML = None + + +def _load_parameters(): + global _PARAMETERS_YAML + + p = pathlib.Path(__file__).with_name('parameters.yaml') + with p.open('r') as f: + _PARAMETERS_YAML = yaml.safe_load(f) + + +def description(parameter): + if _PARAMETERS_YAML is None: + _load_parameters() + + return _PARAMETERS_YAML[parameter]['description'] diff --git a/manila/api/validation/parameters.yaml b/manila/api/validation/parameters.yaml new file mode 120000 index 0000000000..180680da9f --- /dev/null +++ b/manila/api/validation/parameters.yaml @@ -0,0 +1 @@ +../../../api-ref/source/parameters.yaml \ No newline at end of file diff --git a/tools/check_exec.py b/tools/check_exec.py index 458caa522f..b8c5a30bf4 100755 --- a/tools/check_exec.py +++ b/tools/check_exec.py @@ -30,6 +30,9 @@ executable = [] for root, mydir, myfile in os.walk(directory): for f in myfile: path = os.path.join(root, f) + if os.path.islink(path): + # permissions are irrelevant for symlinked files + continue mode = os.lstat(path).st_mode if stat.S_IXUSR & mode: executable.append(path)