From 7fd4c30daf73c85c1218c0e4bd2f8736f6cfb5c9 Mon Sep 17 00:00:00 2001 From: Jesper Hodge <19345795+jesperhodge@users.noreply.github.com> Date: Thu, 16 Nov 2023 15:39:46 -0500 Subject: [PATCH] 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 <49422820+connorhaugh@users.noreply.github.com> * fix: lint * fix: lint * fix: lint --------- Co-authored-by: connorhaugh <49422820+connorhaugh@users.noreply.github.com> --- cms/envs/common.py | 22 +++++++++------------ cms/envs/devstack-experimental.yml | 1 + cms/envs/devstack.py | 29 ++++++++++++++++++++++++++++ cms/envs/production.py | 31 ++++++++++++++++++++++++++++++ cms/urls.py | 6 +++--- 5 files changed, 73 insertions(+), 16 deletions(-) diff --git a/cms/envs/common.py b/cms/envs/common.py index 0cc988657868..a007424cf18f 100644 --- 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 index ad6126086949..8aa2c304af81 100644 --- 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 index dd2f4522b648..275a1fd31e72 100644 --- 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 index 2a77d75d50fc..d0a846d3da21 100644 --- 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 index 973311b1c271..b6dec1825ae6 100644 --- 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'), ]