openstack/manila
Code Issues Proposed changes

api: Add descriptions to API schemas

Browse Source 
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 <stephenfin@redhat.com>
Change-Id: I4ad95085f4960530a259a93dc923ad5fd5677aeb
Partially-implements: bp json-schema-validation
This commit is contained in:
Stephen Finucane 2024-04-25 21:53:14 +01:00
parent 1306849b57
commit 436e7f9982
4 changed files with 127 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
manila/api/schemas/resource_locks.py
View File

@ -12,6 +12,7 @@
from oslo_config import cfg from oslo_config import cfg
from manila.api.validation import helpers
from manila.api.validation import parameter_types from manila.api.validation import parameter_types
from manila.api.validation import response_types from manila.api.validation import response_types
from manila.common import constants from manila.common import constants
@ -28,24 +29,37 @@ create_request_body = {
'resource_id': { 'resource_id': {
'type': 'string', 'type': 'string',
'format': 'uuid', 'format': 'uuid',
'description': helpers.description(
'resource_lock_resource_id'
),
}, },
'lock_reason': { 'lock_reason': {
'type': ['string', 'null'], 'type': ['string', 'null'],
'maxLength': 1023, 'maxLength': 1023,
'description': helpers.description(
'resource_lock_lock_reason_optional'
),
}, },
'resource_type': { 'resource_type': {
'type': ['string', 'null'], 'type': ['string', 'null'],
'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES + (None,), 'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES + (None,),
'default': constants.SHARE_RESOURCE_TYPE, 'default': constants.SHARE_RESOURCE_TYPE,
'description': helpers.description(
'resource_lock_resource_type'
),
}, },
'resource_action': { 'resource_action': {
'type': ['string', 'null'], 'type': ['string', 'null'],
'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,), 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,),
'default': constants.RESOURCE_ACTION_DELETE, 'default': constants.RESOURCE_ACTION_DELETE,
'description': helpers.description(
'resource_lock_resource_action_create_optional'
),
}, },
}, },
'required': ['resource_id'], 'required': ['resource_id'],
'additionalProperties': False, 'additionalProperties': False,
'description': helpers.description('resource_lock_object'),
}, },
}, },
'required': ['resource_lock'], 'required': ['resource_lock'],
@ -61,13 +75,20 @@ update_request_body = {
'resource_action': { 'resource_action': {
'type': ['string', 'null'], 'type': ['string', 'null'],
'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,), 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,),
'description': helpers.description(
'resource_lock_resource_action_optional'
),
}, },
'lock_reason': { 'lock_reason': {
'type': ['string', 'null'], 'type': ['string', 'null'],
'maxLength': 1023, 'maxLength': 1023,
'description': helpers.description(
'resource_lock_lock_reason_optional'
),
}, },
}, },
'additionalProperties': False, 'additionalProperties': False,
'description': helpers.description('resource_lock_object'),
}, },
}, },
'required': ['resource_lock'], 'required': ['resource_lock'],
@ -77,61 +98,94 @@ update_request_body = {
index_request_query = { index_request_query = {
'type': 'object', 'type': 'object',
'properties': { 'properties': {
'limit': parameter_types.multi_params( 'limit': parameter_types.multi_params({
parameter_types.non_negative_integer **parameter_types.non_negative_integer,
), 'description': helpers.description('limit'),
'marker': parameter_types.multi_params({ }),
'type': ['string'], # 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({ 'sort_key': parameter_types.multi_params({
'type': 'string', 'type': 'string',
'default': 'created_at', 'default': 'created_at',
'description': helpers.description('sort_key_resource_locks'),
}), }),
# TODO(stephenfin): Make this an enum of ['asc', 'desc'] # TODO(stephenfin): Make this an enum of ['asc', 'desc']
'sort_dir': parameter_types.multi_params({ 'sort_dir': parameter_types.multi_params({
'type': 'string', 'type': 'string',
'default': 'desc', 'default': 'desc',
'description': helpers.description('sort_dir'),
}), }),
'with_count': parameter_types.multi_params(parameter_types.boolean), 'with_count': parameter_types.multi_params(parameter_types.boolean),
'created_since': parameter_types.multi_params({ 'created_since': parameter_types.multi_params({
'type': 'string', 'type': 'string',
'format': 'date-time', 'format': 'date-time',
'description': helpers.description('created_since_query'),
}), }),
'created_before': parameter_types.multi_params({ 'created_before': parameter_types.multi_params({
'type': 'string', 'type': 'string',
'format': 'date-time', 'format': 'date-time',
'description': helpers.description('created_before_query'),
}), }),
'project_id': parameter_types.multi_params({ 'project_id': parameter_types.multi_params({
'type': ['string', 'null'], 'type': ['string', 'null'],
'format': 'uuid', 'format': 'uuid',
'description': helpers.description(
'resource_lock_project_id_query'
),
}), }),
'user_id': parameter_types.multi_params({ 'user_id': parameter_types.multi_params({
'type': ['string', 'null'], 'type': ['string', 'null'],
'format': 'uuid', 'format': 'uuid',
'description': helpers.description('resource_lock_user_id_query')
}), }),
'resource_id': parameter_types.multi_params({ 'resource_id': parameter_types.multi_params({
'type': ['string', 'null'], 'type': ['string', 'null'],
'format': 'uuid', 'format': 'uuid',
'description': helpers.description(
'resource_lock_resource_id_query'
),
}), }),
'resource_action': parameter_types.multi_params({ 'resource_action': parameter_types.multi_params({
'type': ['string', 'null'], 'type': ['string', 'null'],
'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,), 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS + (None,),
'description': helpers.description(
'resource_lock_resource_action_query'
),
}), }),
'resource_type': parameter_types.multi_params({ 'resource_type': parameter_types.multi_params({
'type': ['string', 'null'], 'type': ['string', 'null'],
'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES + (None,), '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({ 'lock_context': parameter_types.multi_params({
'type': ['string', 'null'], 'type': ['string', 'null'],
'maxLength': 10, 'maxLength': 10,
'description': helpers.description(
'resource_lock_lock_context_query'
),
}), }),
'lock_reason': parameter_types.multi_params({ 'lock_reason': parameter_types.multi_params({
'type': ['string', 'null'], 'type': ['string', 'null'],
'maxLength': 1023, 'maxLength': 1023,
'description': helpers.description(
'resource_lock_lock_reason_query'
),
}), }),
}, },
# TODO(stephenfin): Exclude additional query string parameters in a future # TODO(stephenfin): Exclude additional query string parameters in a future
@ -153,43 +207,70 @@ _resource_lock_response = {
'id': { 'id': {
'type': 'string', 'type': 'string',
'format': 'uuid', 'format': 'uuid',
'description': helpers.description('resource_lock_id'),
}, },
'user_id': { 'user_id': {
'type': 'string', 'type': 'string',
'format': 'uuid', 'format': 'uuid',
'description': helpers.description('resource_lock_user_id'),
}, },
'project_id': { 'project_id': {
'type': 'string', 'type': 'string',
'format': 'uuid', 'format': 'uuid',
'description': helpers.description('resource_lock_project_id'),
}, },
'lock_context': { 'lock_context': {
'type': 'string', 'type': 'string',
'description': helpers.description('resource_lock_lock_context'),
}, },
'resource_type': { 'resource_type': {
'type': 'string', 'type': 'string',
'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES, 'enum': constants.RESOURCE_LOCK_RESOURCE_TYPES,
'description': helpers.description('resource_lock_resource_type'),
}, },
'resource_id': { 'resource_id': {
'type': 'string', 'type': 'string',
'format': 'uuid', 'format': 'uuid',
'description': helpers.description('resource_lock_resource_id'),
}, },
'resource_action': { 'resource_action': {
'type': 'string', 'type': 'string',
'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS, 'enum': constants.RESOURCE_LOCK_RESOURCE_ACTIONS,
'description': helpers.description(
'resource_lock_resource_action'
),
}, },
'lock_reason': { 'lock_reason': {
'type': ['string', 'null'], 'type': ['string', 'null'],
'description': helpers.description('resource_lock_lock_reason'),
}, },
'created_at': { 'created_at': {
'type': 'string', 'type': 'string',
'format': 'date-time', 'format': 'date-time',
'description': helpers.description('created_at'),
}, },
'updated_at': { 'updated_at': {
'type': ['string', 'null'], 'type': ['string', 'null'],
'format': 'date-time', 'format': 'date-time',
'description': helpers.description('updated_at'),
}, },
'links': response_types.links, '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 = { create_response_body = {
@ -210,6 +291,7 @@ index_response_body = {
}, },
'count': { 'count': {
'type': 'integer', 'type': 'integer',
'description': helpers.description('count_without_min_version'),
}, },
'resource_locks_links': response_types.collection_links, 'resource_locks_links': response_types.collection_links,
}, },

32
manila/api/validation/helpers.py Normal file
View File

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

1
manila/api/validation/parameters.yaml Symbolic link
View File

@ -0,0 +1 @@
../../../api-ref/source/parameters.yaml

3
tools/check_exec.py
View File

@ -30,6 +30,9 @@ executable = []
for root, mydir, myfile in os.walk(directory): for root, mydir, myfile in os.walk(directory):
for f in myfile: for f in myfile:
path = os.path.join(root, f) path = os.path.join(root, f)
if os.path.islink(path):
# permissions are irrelevant for symlinked files
continue
mode = os.lstat(path).st_mode mode = os.lstat(path).st_mode
if stat.S_IXUSR & mode: if stat.S_IXUSR & mode:
executable.append(path) executable.append(path)