Merge pull request #21207 from edx/nedbat/api-docs

REST API docs

lms/djangoapps/certificates/apis/v0/views.py

@@ -5,6 +5,7 @@ import logging
 
 import six
 from django.contrib.auth import get_user_model
+from django.utils.decorators import method_decorator
 from edx_rest_framework_extensions import permissions
 from edx_rest_framework_extensions.auth.jwt.authentication import JwtAuthentication
 from edx_rest_framework_extensions.auth.session.authentication import SessionAuthenticationAllowInactiveUser
@@ -20,6 +21,8 @@ from openedx.core.djangoapps.certificates.api import certificates_viewable_for_c
 from openedx.core.djangoapps.content.course_overviews.models import CourseOverview
 from openedx.core.djangoapps.user_api.accounts.api import visible_fields
 from openedx.core.lib.api.authentication import OAuth2AuthenticationAllowInactiveUser
+from openedx.core.openapi import swagger_auto_schema, openapi
+
 
 log = logging.getLogger(__name__)
 User = get_user_model()
@@ -131,21 +134,16 @@ class CertificatesDetailView(GenericAPIView):
         )
 
 
-class CertificatesListView(GenericAPIView):
-    """
+@method_decorator(name='get', decorator=swagger_auto_schema(
+    operation_summary="Get a paginated list of bookmarks for a user.",
+    operation_description=u"""\
         **Use Case**
 
-            * Get the list of viewable course certificates for a specific user.
+        Get the list of viewable course certificates for a specific user.
 
         **Example Request**
 
-            GET /api/certificates/v0/certificates/{username}
-
-        **GET Parameters**
-
-            A GET request must include the following parameters.
-
-            * username: A string representation of an user's username.
+        GET /api/certificates/v0/certificates/{username}
 
         **GET Response Values**
 
@@ -187,8 +185,18 @@ class CertificatesListView(GenericAPIView):
                 "download_url": "http://www.example.com/cert.pdf",
                 "grade": "0.98"
             }]
-    """
-
+        """,
+    manual_parameters=[
+        openapi.Parameter(
+            'username',
+            openapi.IN_PATH,
+            type=openapi.TYPE_STRING,
+            description="The users to get certificates for",
+        ),
+    ],
+))
+class CertificatesListView(GenericAPIView):
+    """REST API endpoints for listing certificates."""
     authentication_classes = (
         JwtAuthentication,
         OAuth2AuthenticationAllowInactiveUser,
@@ -209,16 +217,6 @@ class CertificatesListView(GenericAPIView):
     required_scopes = ['certificates:read']
 
     def get(self, request, username):
-        """
-        Gets the list of viewable course certificates for a specific user.
-
-        Args:
-            request (Request): Django request object.
-            username (string): URI element specifying the user's username.
-
-        Return:
-            A JSON serialized representation of the list of certificates.
-        """
         user_certs = []
         if self._viewable_by_requestor(request, username):
             for user_cert in self._get_certificates_for_user(username):

lms/envs/common.py

@@ -411,9 +411,6 @@ FEATURES = {
     # Sets the default browser support. For more information go to http://browser-update.org/customize.html
     'UNSUPPORTED_BROWSER_ALERT_VERSIONS': "{i:10,f:-3,o:-3,s:-3,c:-3}",
 
-    # Set this to true to make API docs available at /api-docs/.
-    'ENABLE_API_DOCS': False,
-
     # Whether to display the account deletion section the account settings page
     'ENABLE_ACCOUNT_DELETION': True,
 
@@ -2537,6 +2534,9 @@ SWAGGER_SETTINGS = {
     'DEFAULT_INFO': 'openedx.core.openapi.openapi_info',
 }
 
+# How long to cache OpenAPI schemas and UI, in seconds.
+OPENAPI_CACHE_TIMEOUT = 0
+
 ######################### MARKETING SITE ###############################
 EDXMKTG_LOGGED_IN_COOKIE_NAME = 'edxloggedin'
 EDXMKTG_USER_INFO_COOKIE_NAME = 'edx-user-info'

lms/envs/devstack.py

@@ -100,10 +100,6 @@ def should_show_debug_toolbar(request):
         return False
     return True
 
-########################### API DOCS #################################
-
-FEATURES['ENABLE_API_DOCS'] = True
-
 ########################### PIPELINE #################################
 
 PIPELINE['PIPELINE_ENABLED'] = False
@@ -282,6 +278,8 @@ REST_FRAMEWORK['DEFAULT_RENDERER_CLASSES'] += (
     'rest_framework.renderers.BrowsableAPIRenderer',
 )
 
+OPENAPI_CACHE_TIMEOUT = 0
+
 #####################################################################
 # See if the developer has any local overrides.
 if os.path.isfile(join(dirname(abspath(__file__)), 'private.py')):

lms/envs/production.py

@@ -1051,6 +1051,9 @@ ICP_LICENSE_INFO = ENV_TOKENS.get('ICP_LICENSE_INFO', {})
 ############## Settings for CourseGraph ############################
 COURSEGRAPH_JOB_QUEUE = ENV_TOKENS.get('COURSEGRAPH_JOB_QUEUE', DEFAULT_PRIORITY_QUEUE)
 
+# How long to cache OpenAPI schemas and UI, in seconds.
+OPENAPI_CACHE_TIMEOUT = ENV_TOKENS.get('OPENAPI_CACHE_TIMEOUT', 60 * 60)
+
 ########################## Parental controls config  #######################
 
 # The age at which a learner no longer requires parental consent, or None

lms/envs/test.py

@@ -91,8 +91,6 @@ FEATURES['ENABLE_ENROLLMENT_TRACK_USER_PARTITION'] = True
 
 FEATURES['ENABLE_BULK_ENROLLMENT_VIEW'] = True
 
-FEATURES['ENABLE_API_DOCS'] = True
-
 DEFAULT_MOBILE_AVAILABLE = True
 
 # Need wiki for courseware views to work. TODO (vshnayder): shouldn't need it.

lms/tests.py

@@ -28,6 +28,5 @@ class LmsModuleTests(TestCase):
         """
         Tests that requests to the `/api-docs/` endpoint do not raise an exception.
         """
-        assert settings.FEATURES['ENABLE_API_DOCS']
         response = self.client.get('/api-docs/')
         self.assertEqual(200, response.status_code)

lms/urls.py

@@ -86,6 +86,7 @@ urlpatterns = [
     url(r'^user_api/', include('openedx.core.djangoapps.user_api.legacy_urls')),
 
     url(r'^notifier_api/', include('lms.djangoapps.discussion.notifier_api.urls')),
+    url(r'^/api/notifier/', include('lms.djangoapps.discussion.notifier_api.urls')),
 
     url(r'^i18n/', include('django.conf.urls.i18n')),
 
@@ -949,12 +950,19 @@ if settings.BRANCH_IO_KEY:
         url(r'^text-me-the-app', student_views.text_me_the_app, name='text_me_the_app'),
     ]
 
-if settings.FEATURES.get('ENABLE_API_DOCS'):
-    urlpatterns += [
-        url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
-        url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
-        url(r'^api-docs/$', schema_view.with_ui('swagger', cache_timeout=0)),
-    ]
+# API docs.
+urlpatterns += [
+    url(
+        r'^swagger(?P<format>\.json|\.yaml)$',
+        schema_view.without_ui(cache_timeout=settings.OPENAPI_CACHE_TIMEOUT), name='schema-json',
+    ),
+    url(
+        r'^swagger/$',
+        schema_view.with_ui('swagger', cache_timeout=settings.OPENAPI_CACHE_TIMEOUT),
+        name='schema-swagger-ui',
+    ),
+    url(r'^api-docs/$', schema_view.with_ui('swagger', cache_timeout=settings.OPENAPI_CACHE_TIMEOUT)),
+]
 
 # edx-drf-extensions csrf app
 urlpatterns += [