feat: standardize the account retirement pipeline as /api/user/v2/

cms/lib/spectacular.py

@@ -4,15 +4,45 @@
 
 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/",
 )
 
 # Legacy addresses of APIs migrated to /api/authoring/, marked deprecated for

cms/lib/tests/test_spectacular.py

@@ -1,14 +1,17 @@
 """Tests for the CMS drf-spectacular hooks and schema class."""
 
 import re
+from importlib import import_module
 from pathlib import Path
 from unittest import TestCase, mock
 
 from django.conf import settings
 from django.test import SimpleTestCase
+from django.test import TestCase as DjangoTestCase
 from django.urls import path as url_path
 from drf_spectacular.generators import SchemaGenerator
-from drf_spectacular.settings import spectacular_settings
+from drf_spectacular.openapi import AutoSchema
+from drf_spectacular.settings import patched_settings, spectacular_settings
 from rest_framework import serializers, viewsets
 from rest_framework.response import Response
 from rest_framework.settings import api_settings
@@ -20,6 +23,8 @@
     cms_mark_migrated_paths,
     cms_mark_superseded_paths,
 )
+from openedx.core.apidocs import get_api_docs_settings
+from openedx.core.djangoapps.user_api.schema_components import PATCHED_USER_RETIREMENT_STATUS
 
 
 def _endpoint(path):
@@ -73,7 +78,7 @@ def test_every_operation_of_a_superseded_path_is_marked(self):
             assert result["paths"][path]["get"]["deprecated"] is True
 
     def test_both_spellings_of_each_superseded_path_are_listed(self):
-        assert set(SUPERSEDED_PATHS) == {
+        assert {path for path in SUPERSEDED_PATHS if path.startswith("/api/contentstore/")} == {
             "/api/contentstore/v0/youtube_transcripts/{course_id}/chec",
             "/api/contentstore/v0/youtube_transcripts/{course_id}/check",
             "/api/contentstore/v0/youtube_transcripts/{course_id}/uploa",
@@ -156,6 +161,14 @@ def test_both_hooks_are_configured(self):
         assert "cms.lib.spectacular.cms_mark_superseded_paths" in hooks
         assert "cms.lib.spectacular.cms_mark_migrated_paths" in hooks
 
+    def test_no_marking_hook_runs_beside_the_two_this_module_defines(self):
+        assert settings.SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"] == [
+            "drf_spectacular.hooks.postprocess_schema_enums",
+            "cms.lib.spectacular.cms_mark_superseded_paths",
+            "cms.lib.spectacular.cms_mark_migrated_paths",
+            "openedx.core.apidocs.untag_deprecated_operations",
+        ]
+
     def test_the_default_enum_hook_is_kept_alongside_the_new_one(self):
         """Setting the key replaces drf-spectacular's default list, so it is restated."""
         assert "drf_spectacular.hooks.postprocess_schema_enums" in settings.SPECTACULAR_SETTINGS["POSTPROCESSING_HOOKS"]
@@ -200,6 +213,9 @@ def test_is_the_default_schema_class(self):
         """Views without their own ``schema`` pick this up via REST_FRAMEWORK settings."""
         assert api_settings.DEFAULT_SCHEMA_CLASS is CmsAutoSchema
 
+    def test_every_operation_is_described_by_this_class_alone(self):
+        assert CmsAutoSchema.__bases__ == (AutoSchema,)
+
     def test_only_the_colliding_legacy_address_is_suffixed(self):
         patterns = [
             url_path("api/contentstore/v3/home/", _HomeViewSet.as_view({"get": "list"})),
@@ -215,3 +231,140 @@ def test_only_the_colliding_legacy_address_is_suffixed(self):
         # Already distinct from its conforming twin's id, so it keeps its name.
         assert ids["/api/authoring/v4/courses/"] == "v4_courses_list"
         assert ids["/api/contentstore/v4/home/courses/"] == "v4_home_courses_list"
+
+
+#: Every operation of a superseded user address this service serves, with the
+#: name it is published under. The names are the ones both documents have
+#: always carried: a client imports a function per name, so an operation that
+#: comes back under a different one has been taken away from it.
+SUPERSEDED_USER_OPERATION_IDS = {
+    ("/api/user/v1/accounts", "get"): "api_user_v1_accounts_retrieve",
+    ("/api/user/v1/accounts/name_change/", "post"): "api_user_v1_accounts_name_change_create",
+    ("/api/user/v1/accounts/name_change/{username}/confirm/", "post"): (
+        "api_user_v1_accounts_name_change_confirm_create"
+    ),
+    ("/api/user/v1/accounts/search_emails", "post"): "api_user_v1_accounts_search_emails_create",
+    ("/api/user/v1/accounts/{username}", "get"): "api_user_v1_accounts_retrieve_2",
+    ("/api/user/v1/accounts/{username}", "patch"): "api_user_v1_accounts_partial_update",
+    ("/api/user/v1/accounts/{username}/deactivate/", "post"): "api_user_v1_accounts_deactivate_create",
+    ("/api/user/v1/accounts/{username}/image", "delete"): "api_user_v1_accounts_image_destroy",
+    ("/api/user/v1/accounts/{username}/image", "post"): "api_user_v1_accounts_image_create",
+    ("/api/user/v1/accounts/{username}/verification_status/", "get"): (
+        "api_user_v1_accounts_verification_status_retrieve"
+    ),
+    ("/api/user/v1/accounts/{username}/verifications/", "get"): "api_user_v1_accounts_verifications_list",
+    ("/api/user/v1/forum_roles/{name}/users/", "get"): "api_user_v1_forum_roles_users_list",
+    ("/api/user/v1/me", "get"): "api_user_v1_me_retrieve",
+    ("/api/user/v1/preferences/email_opt_in/", "post"): "api_user_v1_preferences_email_opt_in_create",
+    ("/api/user/v1/preferences/time_zones/", "get"): "api_user_v1_preferences_time_zones_list",
+    ("/api/user/v1/preferences/{pref_key}/users/", "get"): "api_user_v1_preferences_users_list",
+    ("/api/user/v1/preferences/{username}", "get"): "api_user_v1_preferences_retrieve",
+    ("/api/user/v1/preferences/{username}", "patch"): "api_user_v1_preferences_partial_update",
+    ("/api/user/v1/preferences/{username}/{preference_key}", "delete"): "api_user_v1_preferences_destroy",
+    ("/api/user/v1/preferences/{username}/{preference_key}", "get"): "api_user_v1_preferences_retrieve_2",
+    ("/api/user/v1/preferences/{username}/{preference_key}", "put"): "api_user_v1_preferences_update",
+    ("/api/user/v1/user_prefs/", "get"): "api_user_v1_user_prefs_list",
+    ("/api/user/v1/user_prefs/{id}/", "get"): "api_user_v1_user_prefs_retrieve",
+    ("/api/user/v1/users/", "get"): "api_user_v1_users_list",
+    ("/api/user/v1/users/{id}/", "get"): "api_user_v1_users_retrieve",
+    ("/api/user/v1/accounts/cancel_retirement/", "post"): "api_user_v1_accounts_cancel_retirement_create",
+    ("/api/user/v1/accounts/retire/", "post"): "api_user_v1_accounts_retire_create",
+    ("/api/user/v1/accounts/retire_misc/", "post"): "api_user_v1_accounts_retire_misc_create",
+    ("/api/user/v1/accounts/retirement_cleanup/", "post"): "api_user_v1_accounts_retirement_cleanup_create",
+    ("/api/user/v1/accounts/retirement_partner_report/", "post"): (
+        "api_user_v1_accounts_retirement_partner_report_create"
+    ),
+    ("/api/user/v1/accounts/retirement_partner_report/", "put"): (
+        "api_user_v1_accounts_retirement_partner_report_update"
+    ),
+    ("/api/user/v1/accounts/retirement_partner_report_cleanup/", "post"): (
+        "api_user_v1_accounts_retirement_partner_report_cleanup_create"
+    ),
+    ("/api/user/v1/accounts/retirement_queue/", "get"): "api_user_v1_accounts_retirement_queue_retrieve",
+    ("/api/user/v1/accounts/retirements_by_status_and_date/", "get"): (
+        "api_user_v1_accounts_retirements_by_status_and_date_retrieve"
+    ),
+    ("/api/user/v1/accounts/update_retirement_status/", "patch"): (
+        "api_user_v1_accounts_update_retirement_status_partial_update"
+    ),
+    ("/api/user/v1/accounts/{username}/retirement_status/", "get"): "api_user_v1_accounts_retirement_status_retrieve",
+}
+
+
+#: The user addresses this service marks superseded.
+SUPERSEDED_USER_ADDRESSES = tuple(path for path in SUPERSEDED_PATHS if path.startswith("/api/user/"))
+
+#: The preference operations this service's own pages call. It serves no
+#: replacement for them, so its document publishes them as current.
+CURRENT_PREFERENCE_OPERATIONS = frozenset({
+    ("/api/user/v1/preferences/{username}", "get"),
+    ("/api/user/v1/preferences/{username}", "patch"),
+    ("/api/user/v1/preferences/{username}/{preference_key}", "delete"),
+    ("/api/user/v1/preferences/{username}/{preference_key}", "get"),
+    ("/api/user/v1/preferences/{username}/{preference_key}", "put"),
+    ("/api/user/v1/preferences/email_opt_in/", "post"),
+})
+
+
+class SupersededUserOperationTest(DjangoTestCase):
+    """
+    The user addresses this service serves beside the LMS, which serves their replacements.
+
+    Both services mount that API at the same addresses and both publish an
+    unauthenticated document of everything they serve. This one marks the
+    addresses it lists as superseded and keeps the name each operation is
+    published under.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        patterns = [
+            entry for entry in import_module(settings.ROOT_URLCONF).urlpatterns
+            if str(entry.pattern).startswith("api/user/")
+        ]
+        # The whole document derives its path prefix from every address the
+        # service serves, which share nothing past the root.
+        with patched_settings({**get_api_docs_settings(), "SCHEMA_PATH_PREFIX": "/"}):
+            cls.schema = SchemaGenerator(patterns=patterns).get_schema(request=None, public=True)
+
+    def _operations(self):
+        """Every operation of the user addresses that have a replacement, as this document carries it."""
+        return {
+            (address, method): self.schema["paths"][address][method]
+            for address, method in SUPERSEDED_USER_OPERATION_IDS
+        }
+
+    def test_this_service_serves_every_address_it_marks(self):
+        """The mark is matched on the exact address, so one this document spells otherwise is never marked."""
+        assert [address for address in SUPERSEDED_USER_ADDRESSES if address not in self.schema["paths"]] == []
+
+    def test_every_operation_of_the_addresses_it_lists_is_marked_superseded(self):
+        marked = {
+            key: operation.get("deprecated") for key, operation in self._operations().items()
+            if key not in CURRENT_PREFERENCE_OPERATIONS
+        }
+        assert marked == dict.fromkeys(set(SUPERSEDED_USER_OPERATION_IDS) - CURRENT_PREFERENCE_OPERATIONS, True)
+
+    def test_the_preference_addresses_its_own_pages_call_are_published_as_current(self):
+        operations = self._operations()
+        marked = {key: "deprecated" in operations[key] for key in CURRENT_PREFERENCE_OPERATIONS}
+        assert marked == dict.fromkeys(CURRENT_PREFERENCE_OPERATIONS, False)
+
+    def test_every_operation_keeps_the_name_it_is_published_under(self):
+        published = {key: operation["operationId"] for key, operation in self._operations().items()}
+        assert published == SUPERSEDED_USER_OPERATION_IDS
+
+    def test_the_retirement_status_model_is_published_as_the_other_service_appends_it(self):
+        """
+        A client generated from this document names a class after each component in it.
+
+        The partial update of a version 1 retirement refers to the
+        retirement-status model here, as it always has. The other service
+        publishes that operation's real body instead and appends the model so
+        that the class keeps its name, and the two describe it identically.
+        """
+        operation = self.schema["paths"]["/api/user/v1/accounts/update_retirement_status/"]["patch"]
+        bodies = {content["schema"]["$ref"] for content in operation["requestBody"]["content"].values()}
+        assert bodies == {"#/components/schemas/PatchedUserRetirementStatus"}
+        assert self.schema["components"]["schemas"]["PatchedUserRetirementStatus"] == PATCHED_USER_RETIREMENT_STATUS

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,7 @@
 from path import Path as path
 
 from openedx.core.djangoapps.plugins.constants import ProjectType, SettingsType
+from openedx.core.djangoapps.user_api.schema_components import 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 +2180,35 @@
 
 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),
+    },
+    # 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
 ]