docs: correct swaggerfile for authoring api

openedx · Nov 3, 2023 · 316a91c · 316a91c
1 parent 2d0c205
commit 316a91c
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 6 deletions.
diff --git a/cms/envs/common.py b/cms/envs/common.py
@@ -2790,7 +2790,7 @@
     '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
+    'PREPROCESSING_HOOKS': ['cms.lib.spectacular.cms_api_filter'],  # restrict spectacular to CMS API endpoints. (cms/lib/spectacular.py)
 }
 
 

diff --git a/cms/lib/spectacular.py b/cms/lib/spectacular.py
@@ -10,10 +10,12 @@ def cms_api_filter(endpoints):
     for (path, path_regex, method, callback) in endpoints:
         # Add only paths to the list that are part of the CMS API
         if (
-            path.startswith("/api/contentstore/v1/xblock") or
-            path.startswith("/api/contentstore/v1/videos") or
-            path.startswith("/api/contentstore/v1/video_transcripts") or
-            path.startswith("/api/contentstore/v1/file_assets")
+            # Don't just replace this with /v1 when switching to a later version of the CMS API.
+            # That would include some unintended endpoints.
+            path.startswith("/api/contentstore/v0/xblock") or
+            path.startswith("/api/contentstore/v0/videos") or
+            path.startswith("/api/contentstore/v0/video_transcripts") or
+            path.startswith("/api/contentstore/v0/file_assets")
         ):
             filtered.append((path, path_regex, method, callback))
     return filtered
diff --git a/cms/urls.py b/cms/urls.py
@@ -342,7 +342,10 @@
     path('api/content_tagging/', include(('openedx.core.djangoapps.content_tagging.urls', 'content_tagging'))),
 ]
 
-# studio-content-api specific API docs (using drf-spectacular and openapi-v3)
+# 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.
+# 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'),