feat: standardize the registration, sign-in and password reset APIs

cms/envs/common.py

@@ -49,6 +49,7 @@
 
 from cms.lib.xblock.authoring_mixin import AuthoringMixin
 from cms.lib.xblock.upstream_sync import UpstreamSyncMixin
+from openedx.core.djangoapps.user_api.schema_components import CREDENTIAL_SCHEMES
 from openedx.core.lib.derived import Derived
 from openedx.core.lib.features_setting_proxy import FeaturesProxy
 from openedx.envs.common import *  # pylint: disable=wildcard-import  # noqa: F403
@@ -1340,6 +1341,13 @@ def _should_send_xblock_events(settings):
         'cms.lib.spectacular.cms_mark_migrated_paths',
         'openedx.core.apidocs.untag_deprecated_operations',
     ],
+    # The sign-in this service serves at the user API's addresses names the
+    # CSRF token, so the token is described here from the definition the other
+    # service appends. Only that credential is described: no operation of this
+    # service names any other.
+    'APPEND_COMPONENTS': {
+        'securitySchemes': {'csrf': CREDENTIAL_SCHEMES['csrf']},
+    },
     # Stripped from each path to derive its tags and operationId, so changing
     # it renames every operationId. Paths are published in full, from the
     # service root, so /api/contentstore and /api/authoring resolve against the

cms/lib/spectacular.py

@@ -4,15 +4,52 @@
 
 from drf_spectacular.openapi import AutoSchema
 
-# Legacy operations superseded by a conforming address under /api/authoring/.
-# Each is listed in the truncated spelling as well as the full one: the routes
+# Legacy operations superseded by a conforming address. Each contentstore one
+# is listed in the truncated spelling as well as the full one: the routes
 # make the final character optional, so both addresses resolve, and which one
 # the generator emits depends on how it renders that regex.
 SUPERSEDED_PATHS = (
     "/api/contentstore/v0/youtube_transcripts/{course_id}/chec",
     "/api/contentstore/v0/youtube_transcripts/{course_id}/check",
     "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa",
     "/api/contentstore/v0/youtube_transcripts/{course_id}/upload",
+    # The user API this service mounts as the LMS does; the LMS serves the replacements.
+    # The preference addresses are left out: this service's own pages change a
+    # preference through them, and it serves no replacement for them.
+    "/api/user/v1/me",
+    "/api/user/v1/accounts",
+    "/api/user/v1/accounts/search_emails",
+    "/api/user/v1/accounts/{username}",
+    "/api/user/v1/accounts/{username}/deactivate/",
+    "/api/user/v1/accounts/{username}/image",
+    "/api/user/v1/accounts/{username}/verification_status/",
+    "/api/user/v1/accounts/{username}/verifications/",
+    "/api/user/v1/accounts/name_change/",
+    "/api/user/v1/accounts/name_change/{username}/confirm/",
+    "/api/user/v1/users/",
+    "/api/user/v1/users/{id}/",
+    "/api/user/v1/user_prefs/",
+    "/api/user/v1/user_prefs/{id}/",
+    "/api/user/v1/preferences/{pref_key}/users/",
+    "/api/user/v1/forum_roles/{name}/users/",
+    "/api/user/v1/preferences/time_zones/",
+    "/api/user/v1/accounts/{username}/retirement_status/",
+    "/api/user/v1/accounts/retirement_queue/",
+    "/api/user/v1/accounts/retirements_by_status_and_date/",
+    "/api/user/v1/accounts/update_retirement_status/",
+    "/api/user/v1/accounts/retirement_cleanup/",
+    "/api/user/v1/accounts/retirement_partner_report/",
+    "/api/user/v1/accounts/retirement_partner_report_cleanup/",
+    "/api/user/v1/accounts/cancel_retirement/",
+    "/api/user/v1/accounts/retire/",
+    "/api/user/v1/accounts/retire_misc/",
+    # The registration, sign-in and password reset addresses of the authentication app.
+    "/api/user/v1/account/registration/",
+    "/api/user/v2/account/registration/",
+    "/api/user/v1/account/password_reset/",
+    "/api/user/v1/account/password_reset/token/validate/",
+    "/api/user/v1/validation/registration",
+    "/api/user/{api_version}/account/login_session/",
 )
 
 # Legacy addresses of APIs migrated to /api/authoring/, marked deprecated for

cms/tests.py

@@ -5,6 +5,7 @@
 from django.urls import path
 
 from openedx.core.apidocs import cached_schema_view
+from openedx.core.djangolib.testing.utils import unresolved_references
 
 
 class CmsModuleTests(TestCase):
@@ -29,6 +30,20 @@ def test_api_docs_schema(self):
         response = self.client.get('/api-docs/schema/')
         assert response.status_code == 200
 
+    def test_every_reference_in_each_served_document_resolves(self):
+        """
+        Each document this service serves defines every component it refers to.
+
+        A component appended through the settings is copied in as written, so
+        one pointing at a model that only another document defines leaves a
+        reference that a client generator refuses.
+        """
+        for address in ('/api-docs/schema/', '/authoring-api/schema/'):
+            response = self.client.get(address, HTTP_ACCEPT='application/vnd.oai.openapi+json')
+            assert response.status_code == 200, address
+            unresolved = unresolved_references(response.json())
+            assert not unresolved, (address, unresolved)
+
     @override_settings(
         OPENAPI_CACHE_TIMEOUT=60,
         CACHES={'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}},

docs/docs_settings.py

@@ -82,7 +82,9 @@
 
 # OpenAPI 3 security schemes, consumed by drf-spectacular. "Basic" uses the
 # OpenAPI 3 http/basic form rather than Swagger 2.0's type: basic.
+# Components the service settings already append are kept.
 SPECTACULAR_SETTINGS["APPEND_COMPONENTS"] = {  # noqa: F405
+    **SPECTACULAR_SETTINGS.get("APPEND_COMPONENTS", {}),  # noqa: F405
     "securitySchemes": {
         "Basic": {
             "type": "http",

lms/envs/common.py

@@ -64,6 +64,10 @@
 from path import Path as path
 
 from openedx.core.djangoapps.plugins.constants import ProjectType, SettingsType
+from openedx.core.djangoapps.user_api.schema_components import (
+    CREDENTIAL_SCHEMES,
+    KEPT_COMPONENT_SCHEMAS,
+)
 from openedx.core.lib.derived import Derived
 from openedx.core.lib.features_setting_proxy import FeaturesProxy
 from openedx.envs.common import *  # pylint: disable=wildcard-import  # noqa: F403
@@ -2179,23 +2183,41 @@
 
 add_optional_apps(OPTIONAL_APPS, INSTALLED_APPS)  # noqa: F405
 
-###################### drf-spectacular (LMS enrollment schema) ######################
+###################### drf-spectacular (LMS API schema) ######################
 SPECTACULAR_SETTINGS = {
-    'TITLE': 'LMS Enrollment API',
+    'TITLE': 'LMS API',
     'VERSION': '0.1.0',
     'SERVE_INCLUDE_SCHEMA': False,
     'PREPROCESSING_HOOKS': ['lms.lib.spectacular.lms_api_filter'],
-    # Mark legacy slashless enrollment addresses deprecated. The enum hook is
-    # drf-spectacular's default, restated because setting this key replaces
-    # the default list.
+    # Mark superseded addresses deprecated. The enum hook is drf-spectacular's
+    # default, restated because setting this key replaces the default list.
     'POSTPROCESSING_HOOKS': [
         'drf_spectacular.hooks.postprocess_schema_enums',
         'lms.lib.spectacular.lms_mark_legacy_paths_deprecated',
+        'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths',
         'openedx.core.apidocs.untag_deprecated_operations',
     ],
+    # Carried by every document built from these settings; Studio generates the
+    # identical model from its own description of the operation.
+    'APPEND_COMPONENTS': {
+        'schemas': dict(KEPT_COMPONENT_SCHEMAS),
+        # How a caller sends each credential the operations of this service
+        # take beside the session cookie. The generator describes the cookie
+        # and nothing else, so an operation taking a token names these and a
+        # client generated from the document can offer the caller a way to
+        # send it.
+        'securitySchemes': dict(CREDENTIAL_SCHEMES),
+    },
+    # Pinned so a second same-named choice field cannot rename these sets; each
+    # names its model so it never claims a plain name another field may need.
+    'ENUM_NAME_OVERRIDES': {
+        'RetirementErasureScopeEnum': 'openedx.core.djangoapps.user_api.v2.serializers.ERASURE_SCOPE_CHOICES',
+        'RetirementBatchResultOutcomeEnum':
+            'openedx.core.djangoapps.user_api.v2.serializers.BATCH_OUTCOME_CHOICES',
+    },
     # Stripped from each path to derive its tags and operationId, so changing
     # it renames every operationId. Paths themselves are emitted in full.
-    'SCHEMA_PATH_PREFIX': '/api/enrollment',
+    'SCHEMA_PATH_PREFIX': r'/api/(enrollment|user)',
     # Serve the Swagger UI and ReDoc assets from drf-spectacular-sidecar rather
     # than drf-spectacular's default unpinned jsdelivr CDN URLs, keeping them
     # self-hosted and version-pinned as the drf-yasg bundles were.

lms/envs/devstack.py

@@ -583,7 +583,7 @@ def should_show_debug_toolbar(request):  # pylint: disable=missing-function-docs
     'COMPLETE',
 ]
 
-###################### drf-spectacular (LMS enrollment schema) ######################
+###################### drf-spectacular (LMS API schema) ######################
 SPECTACULAR_SETTINGS['SERVERS'] = [  # noqa: F405
     {'url': LMS_ROOT_URL, 'description': 'Local'},  # noqa: F405
 ]

lms/envs/production.py

@@ -398,7 +398,7 @@ def get_env_setting(setting):
 MIDDLEWARE.extend(_YAML_TOKENS.get('EXTRA_MIDDLEWARE_CLASSES', []))  # noqa: F405
 
 
-###################### drf-spectacular (LMS enrollment schema) ######################
+###################### drf-spectacular (LMS API schema) ######################
 SPECTACULAR_SETTINGS['SERVERS'] = [  # noqa: F405
     {'url': LMS_ROOT_URL, 'description': 'Local'},  # noqa: F405
 ]

lms/lib/spectacular.py

@@ -4,41 +4,76 @@
 
 from drf_spectacular.openapi import AutoSchema
 
+from openedx.core.djangoapps.user_api.schema import SupersededUserOperations, is_superseded_user_path
+
 LEGACY_V2_PREFIX = "/api/enrollment/v2/"
 
 # The one legacy address that differs from its conforming twin only by the
 # trailing slash, so both tokenize to the same operationId. The other legacy
 # addresses already have distinct ids and keep them.
 COLLIDING_LEGACY_PATH = "/api/enrollment/v2/enrollments"
 
+PUBLISHED_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/")
+
+# Older apps share this prefix, so the view's package decides what is published.
+PUBLISHED_USER_PREFIX = "/api/user/v2/"
+PUBLISHED_USER_VIEW_MODULES = (
+    "openedx.core.djangoapps.user_api.v2.",
+    "openedx.core.djangoapps.profile_images.v2.",
+)
+
+# User operations share one tag where the derived tag would only name a version.
+USER_PATH_PREFIX = "/api/user/"
+USER_TAG = "user"
+
+_VERSION_TAG = re.compile(r"v\d+")
+
+# An address that takes its version as a parameter is left out of the
+# superseded addresses this schema admits, though it is still marked wherever
+# it is published: posting there to sign in publishes the description its
+# handler carries, which is not what that sign-in reads or answers with, and
+# nothing here can replace it.
+_VERSION_PARAMETER = "{api_version}"
+
 
 def _is_legacy_path(path):
     """Conforming routes always end in a slash, so a slashless v2 path is a legacy address."""
     return path.startswith(LEGACY_V2_PREFIX) and not path.endswith("/")
 
 
+def _is_published_user_path(path, callback):
+    """A user address is documented when this version serves it, or when it is a superseded one admitted above."""
+    if is_superseded_user_path(path) and _VERSION_PARAMETER not in path:
+        return True
+    if not path.startswith(PUBLISHED_USER_PREFIX):
+        return False
+    view = getattr(callback, "cls", None)
+    return getattr(view, "__module__", "").startswith(PUBLISHED_USER_VIEW_MODULES)
+
+
 def lms_api_filter(endpoints):
     """
-    Pre-processing hook: keep only enrollment v2 endpoints tagged for the SDK.
+    Pre-processing hook: keep only the endpoints this schema documents.
     """
     filtered = []
-    ENROLLMENT_PATH_PATTERN = re.compile(r"^/api/enrollment/v\d+/")
 
     for path, path_regex, method, callback in endpoints:
-        if ENROLLMENT_PATH_PATTERN.match(path):
+        if PUBLISHED_PATH_PATTERN.match(path) or _is_published_user_path(path, callback):
             filtered.append((path, path_regex, method, callback))
 
     return filtered
 
 
-class LmsAutoSchema(AutoSchema):
+class LmsAutoSchema(SupersededUserOperations, AutoSchema):
     """
     Give the colliding legacy Enrollment v2 address a distinct operationId.
 
     It and its conforming twin tokenize to the same operationId, so
     drf-spectacular would otherwise break the tie with a numeral suffix in
     registration order. The conforming address keeps the clean id; the
     deprecated one is suffixed ``_legacy``.
+
+    A user operation whose derived tag would name a version is tagged ``user``.
     """
 
     def get_operation_id(self):
@@ -48,6 +83,13 @@ def get_operation_id(self):
             return f"{operation_id}_legacy"
         return operation_id
 
+    def get_tags(self):
+        """Name the area whenever the tag derived for a user address would name a version."""
+        tags = super().get_tags()
+        if self.path.startswith(USER_PATH_PREFIX) and tags and _VERSION_TAG.fullmatch(tags[0]):
+            return [USER_TAG]
+        return tags
+
 
 def lms_mark_legacy_paths_deprecated(result, generator, request, public):  # pylint: disable=unused-argument
     """Mark the legacy slashless Enrollment v2 addresses ``deprecated: true``."""