Chore adjust swagger for api gateway (#33694)

* chore: add api.edx.org server and correct route to swagger file endpoints * chore: make server urls for swagger doc depend on env variables * chore: add yaml file server descriptions * chore: rename authoring api route and add description to swagger * Update cms/urls.py Co-authored-by: connorhaugh <[email protected]> * fix: lint * fix: lint * fix: lint --------- Co-authored-by: connorhaugh <[email protected]>
openedx · Nov 16, 2023 · 7fd4c30 · 7fd4c30
1 parent ed37992
commit 7fd4c30
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 16 deletions.
diff --git a/cms/envs/common.py b/cms/envs/common.py
@@ -2783,24 +2783,13 @@
 # disable indexing on date field its coming django-simple-history.
 SIMPLE_HISTORY_DATE_INDEX = False
 
-# This affects the CMS API swagger docs but not the legacy swagger docs under /api-docs/.
-REST_FRAMEWORK['DEFAULT_SCHEMA_CLASS'] = 'drf_spectacular.openapi.AutoSchema'
-
-# These fields override the spectacular settings default values.
-# Any fields not included here will use the default values.
-SPECTACULAR_SETTINGS = {
-    'TITLE': 'CMS API',
-    'DESCRIPTION': 'Experimental API to edit xblocks and course content. Danger: Do not use on running courses!',
-    'VERSION': '1.0.0',
-    'SERVE_INCLUDE_SCHEMA': False,
-    'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter'],  # restrict spectacular to CMS API endpoints. (cms/lib/spectacular.py)
-}
+#### Event bus producing ####
 
 
-#### Event bus producing ####
 def _should_send_xblock_events(settings):
     return settings.FEATURES['ENABLE_SEND_XBLOCK_LIFECYCLE_EVENTS_OVER_BUS']
 
+
 # .. setting_name: EVENT_BUS_PRODUCER_CONFIG
 # .. setting_default: all events disabled
 # .. setting_description: Dictionary of event_types mapped to dictionaries of topic to topic-related configuration.
@@ -2859,4 +2848,11 @@ def _should_send_xblock_events(settings):
                          'course-authoring-xblock-lifecycle', 'enabled')
 derived_collection_entry('EVENT_BUS_PRODUCER_CONFIG', 'org.openedx.content_authoring.xblock.deleted.v1',
                          'course-authoring-xblock-lifecycle', 'enabled')
+
+
+################### Authoring API ######################
+
+# This affects the Authoring API swagger docs but not the legacy swagger docs under /api-docs/.
+REST_FRAMEWORK['DEFAULT_SCHEMA_CLASS'] = 'drf_spectacular.openapi.AutoSchema'
+
 BEAMER_PRODUCT_ID = ""
diff --git a/cms/envs/devstack-experimental.yml b/cms/envs/devstack-experimental.yml
@@ -31,6 +31,7 @@ AUTH_PASSWORD_VALIDATORS:
 -   NAME: common.djangoapps.util.password_policy_validators.MaximumLengthValidator
     OPTIONS:
         max_length: 75
+AUTHORING_API_URL: https://example.com
 AWS_ACCESS_KEY_ID: null
 AWS_QUERYSTRING_AUTH: false
 AWS_S3_CUSTOM_DOMAIN: SET-ME-PLEASE (ex. bucket-name.s3.amazonaws.com)

diff --git a/cms/envs/devstack.py b/cms/envs/devstack.py
@@ -326,3 +326,32 @@ def should_show_debug_toolbar(request):  # lint-amnesty, pylint: disable=missing
 # See if the developer has any local overrides.
 if os.path.isfile(join(dirname(abspath(__file__)), 'private.py')):
     from .private import *  # pylint: disable=import-error,wildcard-import
+
+############## Authoring API drf-spectacular openapi settings ##############
+# These fields override the spectacular settings default values.
+# Any fields not included here will use the default values.
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'Authoring API',
+    'DESCRIPTION': f'''Experimental API to edit xblocks and course content.
+    \n\nDanger: Do not use on running courses!
+    \n\n - How to gain access: Please email the owners of this openedx service.
+    \n - How to use: This API uses oauth2 authentication with the
+    access token endpoint: `{LMS_ROOT_URL}/oauth2/access_token`.
+    Please see separately provided documentation.
+    \n - How to test: You must be logged in as course author for whatever course you want to test with.
+    You can use the [Swagger UI](https://{CMS_BASE}/authoring-api/ui/) to "Try out" the API with your test course. To do this, you must select the "Local" server.
+    \n - Public vs. Local servers: The "Public" server is where you can reach the API externally. The "Local" server is
+    for development with a local edx-platform version,  and for use via the [Swagger UI](https://{CMS_BASE}/authoring-api/ui/).
+    \n - Swaggerfile: [Download link](https://{CMS_BASE}/authoring-api/schema/)''',
+    'VERSION': '0.1.0',
+    'SERVE_INCLUDE_SCHEMA': False,
+    # restrict spectacular to CMS API endpoints (cms/lib/spectacular.py):
+    'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter'],
+    # remove the default schema path prefix to replace it with server-specific base paths:
+    'SCHEMA_PATH_PREFIX': '/api/contentstore',
+    'SCHEMA_PATH_PREFIX_TRIM': '/api/contentstore',
+    'SERVERS': [
+        {'url': AUTHORING_API_URL, 'description': 'Public'},
+        {'url': f'http://{CMS_BASE}/api/contentstore', 'description': 'Local'}
+    ],
+}
diff --git a/cms/envs/production.py b/cms/envs/production.py
@@ -167,6 +167,7 @@ def get_env_setting(setting):
 LMS_INTERNAL_ROOT_URL = ENV_TOKENS.get('LMS_INTERNAL_ROOT_URL', LMS_ROOT_URL)
 ENTERPRISE_API_URL = ENV_TOKENS.get('ENTERPRISE_API_URL', LMS_INTERNAL_ROOT_URL + '/enterprise/api/v1/')
 ENTERPRISE_CONSENT_API_URL = ENV_TOKENS.get('ENTERPRISE_CONSENT_API_URL', LMS_INTERNAL_ROOT_URL + '/consent/api/v1/')
+AUTHORING_API_URL = ENV_TOKENS.get('AUTHORING_API_URL', '')
 # Note that FEATURES['PREVIEW_LMS_BASE'] gets read in from the environment file.
 
 OPENAI_API_KEY = ENV_TOKENS.get('OPENAI_API_KEY', '')
@@ -678,4 +679,34 @@ def get_env_setting(setting):
 ############## Event bus producer ##############
 EVENT_BUS_PRODUCER_CONFIG = merge_producer_configs(EVENT_BUS_PRODUCER_CONFIG,
                                                    ENV_TOKENS.get('EVENT_BUS_PRODUCER_CONFIG', {}))
+
+############## Authoring API drf-spectacular openapi settings ##############
+# These fields override the spectacular settings default values.
+# Any fields not included here will use the default values.
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'Authoring API',
+    'DESCRIPTION': f'''Experimental API to edit xblocks and course content.
+    \n\nDanger: Do not use on running courses!
+    \n\n - How to gain access: Please email the owners of this openedx service.
+    \n - How to use: This API uses oauth2 authentication with the
+    access token endpoint: `{LMS_ROOT_URL}/oauth2/access_token`.
+    Please see separately provided documentation.
+    \n - How to test: You must be logged in as course author for whatever course you want to test with.
+    You can use the [Swagger UI](https://{CMS_BASE}/authoring-api/ui/) to "Try out" the API with your test course. To do this, you must select the "Local" server.
+    \n - Public vs. Local servers: The "Public" server is where you can reach the API externally. The "Local" server is
+    for development with a local edx-platform version,  and for use via the [Swagger UI](https://{CMS_BASE}/authoring-api/ui/).
+    \n - Swaggerfile: [Download link](https://{CMS_BASE}/authoring-api/schema/)''',
+    'VERSION': '0.1.0',
+    'SERVE_INCLUDE_SCHEMA': False,
+    # restrict spectacular to CMS API endpoints (cms/lib/spectacular.py):
+    'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter'],
+    # remove the default schema path prefix to replace it with server-specific base paths:
+    'SCHEMA_PATH_PREFIX': '/api/contentstore',
+    'SCHEMA_PATH_PREFIX_TRIM': '/api/contentstore',
+    'SERVERS': [
+        {'url': AUTHORING_API_URL, 'description': 'Public'},
+        {'url': f'https://{CMS_BASE}/api/contentstore', 'description': 'Local'},
+    ],
+}
+
 BEAMER_PRODUCT_ID = ENV_TOKENS.get('BEAMER_PRODUCT_ID', BEAMER_PRODUCT_ID)
diff --git a/cms/urls.py b/cms/urls.py
@@ -344,9 +344,9 @@
 
 # Authoring-api specific API docs (using drf-spectacular and openapi-v3).
 # This is separate from and in addition to the full studio swagger documentation already existing at /api-docs.
-# Custom settings are provided in SPECTACULAR_SETTINGS in cms/envs/common.py.
+# Custom settings are provided in SPECTACULAR_SETTINGS as environment variables
 # Filter function in cms/lib/spectacular.py determines paths that are swagger-documented.
 urlpatterns += [
-    re_path('^cms-api/ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
-    re_path('^cms-api/schema/', SpectacularAPIView.as_view(), name='schema'),
+    re_path('^authoring-api/ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
+    re_path('^authoring-api/schema/', SpectacularAPIView.as_view(), name='schema'),
 ]