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

cms/envs/common.py

@@ -49,6 +49,10 @@
 
 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,
+    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
@@ -1338,8 +1342,30 @@ def _should_send_xblock_events(settings):
         'drf_spectacular.hooks.postprocess_schema_enums',
         'cms.lib.spectacular.cms_mark_superseded_paths',
         'cms.lib.spectacular.cms_mark_migrated_paths',
+        # Studio mounts the user API at the same addresses the LMS does, and
+        # both services publish an unauthenticated document at /api-docs/, so
+        # an address superseded in one is superseded in the other. The list of
+        # them and the hook that reads it are shared rather than restated here,
+        # which is what stops a client generated from Studio's document from
+        # offering an address as current that the LMS document marks as
+        # superseded.
+        'openedx.core.djangoapps.user_api.schema.mark_superseded_user_paths',
         'openedx.core.apidocs.untag_deprecated_operations',
     ],
+    # This service also serves the user API, which names a component no
+    # operation of it refers to any more. It is appended here, from the
+    # definition the other service appends as well, so that a client generated
+    # from either service's document carries that class. Every document built
+    # from these settings carries it, the service-wide one included.
+    'APPEND_COMPONENTS': {
+        'schemas': dict(KEPT_COMPONENT_SCHEMAS),
+        # 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, and a client generated from either service's
+        # document can send it. Only that credential is described: no
+        # operation of this service names any other.
+        '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,6 +4,8 @@
 
 from drf_spectacular.openapi import AutoSchema
 
+from openedx.core.djangoapps.user_api.schema import SupersededUserOperations
+
 # 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
 # make the final character optional, so both addresses resolve, and which one
@@ -72,14 +74,22 @@ def cms_mark_superseded_paths(result, generator, request, public):  # pylint: di
     return result
 
 
-class CmsAutoSchema(AutoSchema):
+class CmsAutoSchema(SupersededUserOperations, AutoSchema):
     """
     Give a colliding legacy address a distinct operationId.
 
     Where a legacy mount and its conforming mount tokenize to the same
     operationId, 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``.
+
+    This service also serves the user API at the same addresses the service
+    that replaces it does, and both publish an unauthenticated document of
+    everything they serve. The shared behaviour describes those addresses the
+    one way, so that a client generated from either document reads the same
+    signature and the same success code for the same request; it is taken from
+    where that API's own schema lives rather than copied, because two copies
+    of a description drift.
     """
 
     def get_operation_id(self):

docs/docs_settings.py

@@ -19,6 +19,7 @@
 )
 from lms.envs.common import *  # pylint: disable=wildcard-import  # noqa: F403
 from openedx.core.apidocs import get_api_docs_settings
+from openedx.core.djangoapps.user_api.schema_components import KEPT_COMPONENT_SCHEMAS
 from openedx.core.lib.derived import derive_settings
 
 # Turn on all the boolean feature flags, so that conditionally included
@@ -82,7 +83,22 @@
 
 # OpenAPI 3 security schemes, consumed by drf-spectacular. "Basic" uses the
 # OpenAPI 3 http/basic form rather than Swagger 2.0's type: basic.
+#
+# Whatever the service settings already append is carried through rather than
+# replaced, both the keys beside "schemas" and the component names under it:
+# those names are what the published reference is expected to carry, and one
+# dropped here goes out of the generated reference, and out of every client
+# built from it, without changing any count that would show it had gone.
+#
+# The components a service appends although nothing refers to them are named
+# again here, through the one definition both services read, because the
+# reference is expected to carry them whatever else a service appends.
 SPECTACULAR_SETTINGS["APPEND_COMPONENTS"] = {  # noqa: F405
+    **SPECTACULAR_SETTINGS.get("APPEND_COMPONENTS", {}),  # noqa: F405
+    "schemas": {
+        **SPECTACULAR_SETTINGS.get("APPEND_COMPONENTS", {}).get("schemas", {}),  # noqa: F405
+        **KEPT_COMPONENT_SCHEMAS,
+    },
     "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,46 @@
 
 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, including the
+    # service-wide one, which overlays its own keys over them. The other
+    # service that serves this API appends the same components, read from the
+    # same definition, so neither document names one the other does not.
+    '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),
+    },
+    # A set of choices is published as its own model, named after the field
+    # carrying it while one field of the service carries that name alone. The
+    # moment a second field of the same name carries a different set, both are
+    # renamed after the models they sit in, so the plain name disappears and a
+    # client generated from the document loses that class. The names below are
+    # fixed here so that the sets keep them whatever else the service grows.
+    'ENUM_NAME_OVERRIDES': {
+        'ScopeEnum': 'openedx.core.djangoapps.user_api.v2.serializers.ERASURE_SCOPE_CHOICES',
+        'OutcomeEnum': '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,53 +4,107 @@
 
 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+/")
+
+# The user addresses this schema documents are the ones the version below
+# serves, and beside each of those the address it supersedes. Apps older than
+# that version are mounted under the same ``/api/user/v2/`` prefix, so matching
+# the prefix alone would publish endpoints described nowhere here; the packages
+# a view may come from decide instead. One resource of this version lives in
+# the app that owns it rather than in the user API's own package.
+PUBLISHED_USER_PREFIX = "/api/user/v2/"
+PUBLISHED_USER_VIEW_MODULES = (
+    "openedx.core.djangoapps.user_api.v2.",
+    "openedx.core.djangoapps.profile_images.v2.",
+)
+
+# Every user address, whatever its version, belongs to one tag group. A tag is
+# the first path segment left once the configured prefix is removed, which in a
+# document that trims ``/api/user`` is the version, so user operations would be
+# grouped with the enrollment operations that carry the same version. A document
+# that trims nothing already derives a tag naming an area, and regrouping its
+# operations would move them in every client generated from it.
+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``.
+    Keep colliding addresses distinct and group each operation under its own area.
+
+    The slashless Enrollment v2 address tokenizes to the id of its conforming
+    twin, so the two would be told apart only by a numeral suffix, which says
+    which of the two addresses sorts first rather than anything about the
+    operation; it is suffixed ``_legacy`` instead, leaving the conforming
+    address the clean id, and the address listed above keeps the name it is
+    already published under. Each operation keeps the tag the generator derives
+    for it unless that tag names a version, because a client generated from a
+    document groups the operations it offers by tag.
     """
 
     def get_operation_id(self):
-        """Suffix the colliding legacy address so the pair never shares an operationId."""
+        """Keep each address that tokenizes to another one's id distinct from it."""
         operation_id = super().get_operation_id()
         if self.path == COLLIDING_LEGACY_PATH:
             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``."""
+    """Mark every legacy enrollment address ``deprecated: true``."""
     for path, path_item in result.get("paths", {}).items():
         if not _is_legacy_path(path):
             continue