From 2f7fd9d49e1456217fd1bcbb3f3b7394e691f1b1 Mon Sep 17 00:00:00 2001 From: Witold Bedyk Date: Tue, 5 Jun 2018 17:33:51 +0200 Subject: [PATCH] Document API methods in policy code Updated the documentation strings to be more descriptive. Change-Id: I33eeef1c873009cab9c5ff054cc0d011a5b5f53f Story: 2001233 Task: 20006 --- monasca_api/policies/alarms.py | 24 +++++++++++++----------- monasca_api/policies/delegate.py | 4 ++-- monasca_api/policies/healthcheck.py | 2 +- monasca_api/policies/metrics.py | 8 ++++---- monasca_api/policies/notifications.py | 12 ++++++------ monasca_api/policies/versions.py | 3 ++- 6 files changed, 28 insertions(+), 25 deletions(-) diff --git a/monasca_api/policies/alarms.py b/monasca_api/policies/alarms.py index 7ce8ca073..abedb2358 100644 --- a/monasca_api/policies/alarms.py +++ b/monasca_api/policies/alarms.py @@ -21,7 +21,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:definition:post', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Post alarm definition role', + description='Create an alarm definition.', operations=[ { 'path': '/v2.0/alarm-definitions/', @@ -32,7 +32,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:definition:get', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Get alarm definition role', + description='List or get the details of the specified alarm definition.', operations=[ { 'path': '/v2.0/alarm-definitions/{alarm_definition_id}', @@ -47,7 +47,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:definition:put', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Put alarm definition role', + description='Update/Replace the specified alarm definition.', operations=[ { 'path': '/v2.0/alarm-definitions/{alarm_definition_id}', @@ -58,7 +58,8 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:definition:patch', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Patch alarm definition role', + description='Update selected parameters of the specified alarm definition, ' + 'and enable/disable its actions.', operations=[ { 'path': '/v2.0/alarm-definitions/{alarm_definition_id}', @@ -69,7 +70,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:definition:delete', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Delete alarm definition role', + description='Delete the specified alarm definition.', operations=[ { 'path': '/v2.0/alarm-definitions/{alarm_definition_id}', @@ -80,7 +81,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:put', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Put alarm role', + description='Update/Replace the entire state of the specified alarm.', operations=[ { 'path': '/v2.0/alarms/{alarm_id}', @@ -91,7 +92,8 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:patch', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Patch alarm role', + description='Update selected parameters of a specified alarm,' + ' set the alarm state and enable/disable it.', operations=[ { 'path': '/v2.0/alarms/{alarm_id}', @@ -102,7 +104,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:delete', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Delete alarm role', + description='Delete the specified alarm.', operations=[ { 'path': '/v2.0/alarms/{alarm_id}', @@ -113,7 +115,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:get', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Get alarm role', + description='List or get the details of the specified alarm.', operations=[ { 'path': '/v2.0/alarms/', @@ -128,7 +130,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:count', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Count alarm role', + description='Get the number of alarms that match the criteria.', operations=[ { 'path': '/v2.0/alarms/count/', @@ -139,7 +141,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:alarms:state_history', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Alarm state history role', + description='List alarm state history for alarms.', operations=[ { 'path': '/v2.0/alarms/state-history', diff --git a/monasca_api/policies/delegate.py b/monasca_api/policies/delegate.py index d5429588b..7b0900154 100644 --- a/monasca_api/policies/delegate.py +++ b/monasca_api/policies/delegate.py @@ -20,8 +20,8 @@ rules = [ policy.RuleDefault( name='api:delegate', check_str=DELEGATE_AUTHORIZED_ROLES, - description='The rules that allowes to access the API on' - ' behalf of another tenant role', + description='The rules which allow to access the API on' + ' behalf of another tenant.', ) ] diff --git a/monasca_api/policies/healthcheck.py b/monasca_api/policies/healthcheck.py index c1dd9a142..e91b94a39 100644 --- a/monasca_api/policies/healthcheck.py +++ b/monasca_api/policies/healthcheck.py @@ -20,7 +20,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:healthcheck', check_str=HEALTHCHECK_ROLES, - description='Healthcheck role', + description='Check healthiness.', operations=[ {'path': '/healthcheck', 'method': 'GET'} ] diff --git a/monasca_api/policies/metrics.py b/monasca_api/policies/metrics.py index 2fa7810e1..79e6eb126 100644 --- a/monasca_api/policies/metrics.py +++ b/monasca_api/policies/metrics.py @@ -23,7 +23,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:metrics:get', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Get metrics role', + description='List metrics, measurements, metric statistics or metric names.', operations=[ {'path': '/v2.0/metrics', 'method': 'GET'}, {'path': '/v2.0/metrics/measurements', 'method': 'GET'}, @@ -34,7 +34,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:metrics:post', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + AGENT_AUTHORIZED_ROLES, - description='Post metrics role', + description='Create metrics.', operations=[ {'path': '/v2.0/metrics', 'method': 'POST'} ] @@ -42,7 +42,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:metrics:dimension:values', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Get metrics dimension values role', + description='List dimension values.', operations=[ {'path': '/v2.0/metrics/dimensions/names/values', 'method': 'GET'} ] @@ -50,7 +50,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:metrics:dimension:names', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Get metrics dimension names role', + description='List dimension names.', operations=[ {'path': '/v2.0/metrics/dimensions/names', 'method': 'GET'} ] diff --git a/monasca_api/policies/notifications.py b/monasca_api/policies/notifications.py index 63347bcea..e98b3b28f 100644 --- a/monasca_api/policies/notifications.py +++ b/monasca_api/policies/notifications.py @@ -22,7 +22,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:notifications:put', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Put notifications role', + description='Update the specified notification method.', operations=[ { 'path': '/v2.0/notification-methods/{notification_method_id}', @@ -33,7 +33,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:notifications:patch', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Patch notifications role', + description='Update selected parameters of the specified notification method.', operations=[ { 'path': '/v2.0/notification-methods/{notification_method_id}', @@ -44,7 +44,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:notifications:delete', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Delete notifications role', + description='Delete the specified notification method.', operations=[ { 'path': '/v2.0/notification-methods/{notification_method_id}', @@ -55,7 +55,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:notifications:get', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Get notifications role', + description='List or get the details of the specified notification method.', operations=[ { 'path': '/v2.0/notification-methods', @@ -70,7 +70,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:notifications:post', check_str=DEFAULT_AUTHORIZED_ROLES, - description='Post notifications role', + description='Create a notification method.', operations=[ { 'path': '/v2.0/notification-methods', @@ -81,7 +81,7 @@ rules = [ policy.DocumentedRuleDefault( name='api:notifications:type', check_str=DEFAULT_AUTHORIZED_ROLES + ' or ' + READ_ONLY_AUTHORIZED_ROLES, - description='Get notifications type role', + description='List supported notification method types.', operations=[ { 'path': '/v2.0/notification-methods/types', diff --git a/monasca_api/policies/versions.py b/monasca_api/policies/versions.py index c6c0cbc97..d0add788f 100644 --- a/monasca_api/policies/versions.py +++ b/monasca_api/policies/versions.py @@ -20,7 +20,8 @@ rules = [ policy.DocumentedRuleDefault( name='api:versions', check_str=VERSIONS_ROLES, - description='Get versions role', + description='List supported versions ' + 'or get the details about the specified version of Monasca API.', operations=[ {'path': '/', 'method': 'GET'}, {'path': '/v2.0', 'method': 'GET'}