From ac7c5f8648428202873185b71c34d268dfdafe5f Mon Sep 17 00:00:00 2001 From: Ryan Petrello Date: Fri, 2 Feb 2018 13:00:54 -0500 Subject: [PATCH] clean up API markdown docs --- awx/api/generics.py | 2 +- awx/api/templates/api/ad_hoc_command_relaunch.md | 3 +++ awx/api/templates/api/api_v1_config_view.md | 15 ++++++++++++++- awx/api/templates/api/auth_token_view.md | 10 ++++++++-- .../templates/api/dashboard_jobs_graph_view.md | 2 ++ .../templates/api/inventory_root_groups_list.md | 2 ++ awx/api/templates/api/job_cancel.md | 7 ++++++- awx/api/templates/api/job_relaunch.md | 4 ++-- awx/api/templates/api/job_start.md | 7 ++++++- awx/api/templates/api/list_api_view.md | 2 ++ awx/api/templates/api/list_create_api_view.md | 2 +- .../templates/api/retrieve_destroy_api_view.md | 4 ++++ awx/api/templates/api/setting_logging_test.md | 1 + awx/api/templates/api/sub_list_api_view.md | 3 +-- awx/api/templates/api/sub_list_create_api_view.md | 2 +- awx/api/views.py | 12 +++++++----- 16 files changed, 61 insertions(+), 17 deletions(-) create mode 100644 awx/api/templates/api/ad_hoc_command_relaunch.md create mode 100644 awx/api/templates/api/setting_logging_test.md diff --git a/awx/api/generics.py b/awx/api/generics.py index 19a1fac19e..396655c660 100644 --- a/awx/api/generics.py +++ b/awx/api/generics.py @@ -217,7 +217,7 @@ class APIView(views.APIView): context['deprecated'] = True description = render_to_string(template_list, context) - if context.get('deprecated'): + if context.get('deprecated') and context.get('swagger_method') is None: # render deprecation messages at the very top description = '\n'.join([render_to_string('api/_deprecated.md', context), description]) return description diff --git a/awx/api/templates/api/ad_hoc_command_relaunch.md b/awx/api/templates/api/ad_hoc_command_relaunch.md new file mode 100644 index 0000000000..fdddd4b6ba --- /dev/null +++ b/awx/api/templates/api/ad_hoc_command_relaunch.md @@ -0,0 +1,3 @@ +Relaunch an Ad Hoc Command: + +Make a POST request to this resource to launch a job. If any passwords or variables are required then they should be passed in via POST data. In order to determine what values are required in order to launch a job based on this job template you may make a GET request to this endpoint. diff --git a/awx/api/templates/api/api_v1_config_view.md b/awx/api/templates/api/api_v1_config_view.md index d99b97d553..d037ff4408 100644 --- a/awx/api/templates/api/api_v1_config_view.md +++ b/awx/api/templates/api/api_v1_config_view.md @@ -1,4 +1,5 @@ -Site configuration settings and general information. +{% ifmeth GET %} +# Site configuration settings and general information Make a GET request to this resource to retrieve the configuration containing the following fields (some fields may not be visible to all users): @@ -11,6 +12,10 @@ the following fields (some fields may not be visible to all users): * `license_info`: Information about the current license. * `version`: Version of Ansible Tower package installed. * `eula`: The current End-User License Agreement +{% endifmeth %} + +{% ifmeth POST %} +# Install or update an existing license (_New in Ansible Tower 2.0.0_) Make a POST request to this resource as a super user to install or update the existing license. The license data itself can @@ -18,3 +23,11 @@ be POSTed as a normal json data structure. (_New in Ansible Tower 2.1.1_) The POST must include a `eula_accepted` boolean element indicating acceptance of the End-User License Agreement. +{% endifmeth %} + +{% ifmeth DELETE %} +# Delete an existing license + +(_New in Ansible Tower 2.0.0_) Make a DELETE request to this resource as a super +user to delete the existing license +{% endifmeth %} diff --git a/awx/api/templates/api/auth_token_view.md b/awx/api/templates/api/auth_token_view.md index 69078842d4..5df4892370 100644 --- a/awx/api/templates/api/auth_token_view.md +++ b/awx/api/templates/api/auth_token_view.md @@ -1,3 +1,5 @@ +{% ifmeth POST %} +# Generate an Auth Token Make a POST request to this resource with `username` and `password` fields to obtain an authentication token to use for subsequent requests. @@ -32,6 +34,10 @@ agent that originally obtained it. Each request that uses the token for authentication will refresh its expiration timestamp and keep it from expiring. A token only expires when it is not used for the configured timeout interval (default 1800 seconds). +{% endifmeth %} -A DELETE request with the token set will cause the token to be invalidated and -no further requests can be made with it. +{% ifmeth DELETE %} +# Delete an Auth Token +A DELETE request with the token header set will cause the token to be +invalidated and no further requests can be made with it. +{% endifmeth %} diff --git a/awx/api/templates/api/dashboard_jobs_graph_view.md b/awx/api/templates/api/dashboard_jobs_graph_view.md index cab9a25a2c..fa3c42497f 100644 --- a/awx/api/templates/api/dashboard_jobs_graph_view.md +++ b/awx/api/templates/api/dashboard_jobs_graph_view.md @@ -1,3 +1,5 @@ +# View Statistics for Job Runs + Make a GET request to this resource to retrieve aggregate statistics about job runs suitable for graphing. ## Parmeters and Filtering diff --git a/awx/api/templates/api/inventory_root_groups_list.md b/awx/api/templates/api/inventory_root_groups_list.md index b051ec94f6..41df816c10 100644 --- a/awx/api/templates/api/inventory_root_groups_list.md +++ b/awx/api/templates/api/inventory_root_groups_list.md @@ -1,3 +1,4 @@ +{% ifmeth GET %} # List Root {{ model_verbose_name_plural|title }} for {{ parent_model_verbose_name|title|anora }}: Make a GET request to this resource to retrieve a list of root (top-level) @@ -5,3 +6,4 @@ Make a GET request to this resource to retrieve a list of root (top-level) {{ parent_model_verbose_name }}. {% include "api/_list_common.md" %} +{% endifmeth %} diff --git a/awx/api/templates/api/job_cancel.md b/awx/api/templates/api/job_cancel.md index f0acece331..9afb6d5031 100644 --- a/awx/api/templates/api/job_cancel.md +++ b/awx/api/templates/api/job_cancel.md @@ -1,10 +1,15 @@ -# Cancel Job +{% ifmeth GET %} +# Determine if a Job can be cancelled Make a GET request to this resource to determine if the job can be cancelled. The response will include the following field: * `can_cancel`: Indicates whether this job can be canceled (boolean, read-only) +{% endifmeth %} +{% ifmeth POST %} +# Cancel a Job Make a POST request to this resource to cancel a pending or running job. The response status code will be 202 if successful, or 405 if the job cannot be canceled. +{% endifmeth %} diff --git a/awx/api/templates/api/job_relaunch.md b/awx/api/templates/api/job_relaunch.md index 7e9ea316ce..e0946435ff 100644 --- a/awx/api/templates/api/job_relaunch.md +++ b/awx/api/templates/api/job_relaunch.md @@ -1,3 +1,3 @@ -Relaunch a job: +Relaunch a Job: -Make a POST request to this resource to launch a job. If any passwords or variables are required then they should be passed in via POST data. In order to determine what values are required in order to launch a job based on this job template you may make a GET request to this endpoint. \ No newline at end of file +Make a POST request to this resource to launch a job. If any passwords or variables are required then they should be passed in via POST data. In order to determine what values are required in order to launch a job based on this job template you may make a GET request to this endpoint. diff --git a/awx/api/templates/api/job_start.md b/awx/api/templates/api/job_start.md index 4b15ebc76b..43104dd2bc 100644 --- a/awx/api/templates/api/job_start.md +++ b/awx/api/templates/api/job_start.md @@ -1,4 +1,5 @@ -# Start Job +{% ifmeth GET %} +# Determine if a Job can be started Make a GET request to this resource to determine if the job can be started and whether any passwords are required to start the job. The response will include @@ -7,10 +8,14 @@ the following fields: * `can_start`: Flag indicating if this job can be started (boolean, read-only) * `passwords_needed_to_start`: Password names required to start the job (array, read-only) +{% endifmeth %} +{% ifmeth POST %} +# Start a Job Make a POST request to this resource to start the job. If any passwords are required, they must be passed via POST data. If successful, the response status code will be 202. If any required passwords are not provided, a 400 status code will be returned. If the job cannot be started, a 405 status code will be returned. +{% endifmeth %} diff --git a/awx/api/templates/api/list_api_view.md b/awx/api/templates/api/list_api_view.md index c45b46c40f..69f4d8fa59 100644 --- a/awx/api/templates/api/list_api_view.md +++ b/awx/api/templates/api/list_api_view.md @@ -1,3 +1,4 @@ +{% ifmeth GET %} # List {{ model_verbose_name_plural|title }}: Make a GET request to this resource to retrieve the list of @@ -6,3 +7,4 @@ Make a GET request to this resource to retrieve the list of {% include "api/_list_common.md" %} {% include "api/_new_in_awx.md" %} +{% endifmeth %} diff --git a/awx/api/templates/api/list_create_api_view.md b/awx/api/templates/api/list_create_api_view.md index 400eeade18..89a9c19f61 100644 --- a/awx/api/templates/api/list_create_api_view.md +++ b/awx/api/templates/api/list_create_api_view.md @@ -1,6 +1,6 @@ {% include "api/list_api_view.md" %} -# Create {{ model_verbose_name_plural|title }}: +# Create {{ model_verbose_name|title|anora }}: Make a POST request to this resource with the following {{ model_verbose_name }} fields to create a new {{ model_verbose_name }}: diff --git a/awx/api/templates/api/retrieve_destroy_api_view.md b/awx/api/templates/api/retrieve_destroy_api_view.md index 3b1da52551..ae2d644d3d 100644 --- a/awx/api/templates/api/retrieve_destroy_api_view.md +++ b/awx/api/templates/api/retrieve_destroy_api_view.md @@ -2,15 +2,19 @@ ### Note: starting from api v2, this resource object can be accessed via its named URL. {% endif %} +{% ifmeth GET %} # Retrieve {{ model_verbose_name|title|anora }}: Make GET request to this resource to retrieve a single {{ model_verbose_name }} record containing the following fields: {% include "api/_result_fields_common.md" %} +{% endifmeth %} +{% ifmeth DELETE %} # Delete {{ model_verbose_name|title|anora }}: Make a DELETE request to this resource to delete this {{ model_verbose_name }}. +{% endifmeth %} {% include "api/_new_in_awx.md" %} diff --git a/awx/api/templates/api/setting_logging_test.md b/awx/api/templates/api/setting_logging_test.md new file mode 100644 index 0000000000..149fac28ae --- /dev/null +++ b/awx/api/templates/api/setting_logging_test.md @@ -0,0 +1 @@ +# Test Logging Configuration diff --git a/awx/api/templates/api/sub_list_api_view.md b/awx/api/templates/api/sub_list_api_view.md index f657c0b802..f367674c66 100644 --- a/awx/api/templates/api/sub_list_api_view.md +++ b/awx/api/templates/api/sub_list_api_view.md @@ -6,6 +6,5 @@ Make a GET request to this resource to retrieve a list of {{ parent_model_verbose_name }}. {% include "api/_list_common.md" %} -{% endifmeth %} - {% include "api/_new_in_awx.md" %} +{% endifmeth %} diff --git a/awx/api/templates/api/sub_list_create_api_view.md b/awx/api/templates/api/sub_list_create_api_view.md index b83233beaa..a458404e81 100644 --- a/awx/api/templates/api/sub_list_create_api_view.md +++ b/awx/api/templates/api/sub_list_create_api_view.md @@ -1,6 +1,6 @@ {% include "api/sub_list_api_view.md" %} -# Create {{ model_verbose_name_plural|title }} for {{ parent_model_verbose_name|title|anora }}: +# Create {{ model_verbose_name|title|anora }} for {{ parent_model_verbose_name|title|anora }}: Make a POST request to this resource with the following {{ model_verbose_name }} fields to create a new {{ model_verbose_name }} associated with this diff --git a/awx/api/views.py b/awx/api/views.py index 32b4fea18d..6f888f9472 100644 --- a/awx/api/views.py +++ b/awx/api/views.py @@ -192,7 +192,7 @@ class ApiRootView(APIView): swagger_topic = 'Versioning' def get(self, request, format=None): - ''' list supported API versions ''' + ''' List supported API versions ''' v1 = reverse('api:api_v1_root_view', kwargs={'version': 'v1'}) v2 = reverse('api:api_v2_root_view', kwargs={'version': 'v2'}) @@ -214,7 +214,7 @@ class ApiVersionRootView(APIView): swagger_topic = 'Versioning' def get(self, request, format=None): - ''' list top level resources ''' + ''' List top level resources ''' data = OrderedDict() data['authtoken'] = reverse('api:auth_token_view', request=request) data['ping'] = reverse('api:api_v1_ping_view', request=request) @@ -280,7 +280,7 @@ class ApiV1PingView(APIView): swagger_topic = 'System Configuration' def get(self, request, format=None): - """Return some basic information about this instance. + """Return some basic information about this instance Everything returned here should be considered public / insecure, as this requires no auth and is intended for use by the installer process. @@ -316,7 +316,7 @@ class ApiV1ConfigView(APIView): self.permission_denied(request) # Raises PermissionDenied exception. def get(self, request, format=None): - '''Return various sitewide configuration settings.''' + '''Return various sitewide configuration settings''' if request.user.is_superuser or request.user.is_system_auditor: license_data = get_license(show_key=True) @@ -754,11 +754,12 @@ class ScheduleUnifiedJobsList(SubListAPIView): class AuthView(APIView): + ''' List enabled single-sign-on endpoints ''' authentication_classes = [] permission_classes = (AllowAny,) new_in_240 = True - swagger_topic = 'Authentication' + swagger_topic = 'System Configuration' def get(self, request): from rest_framework.reverse import reverse @@ -4780,6 +4781,7 @@ class NotificationTemplateDetail(RetrieveUpdateDestroyAPIView): class NotificationTemplateTest(GenericAPIView): + '''Test a Notification Template''' view_name = _('Notification Template Test') model = NotificationTemplate