feat: add more authentication information to swagger (#35674)

* feat: add more authentication information to swagger
* updates the `docs-settings` to make the generated swagger
  `securityDefinitions` include both JWT and CSRF methods, as well as
  basic. A few linter fixes happened as a side effect.
* Put in wordier descriptions for all three, since we don't have great
  shared documentation about authn/authz.
* Added CSRF to `login_session`, which also serves as a proof of concept
  for other endpoits
* Also regenerated the swagger doc, which picked up some extra changes.

Generated swagger now has help and allows extra auth methods so some
preveiously unusable endpoints can be hit.

FIXES: APER-3554

docs/docs_settings.py

@@ -4,7 +4,7 @@ Basically the LMS devstack settings plus a few items needed to successfully
 import all the Studio code.
 """
 
-
+from textwrap import dedent
 import os
 
 from openedx.core.lib.derived import derive_settings
@@ -27,18 +27,71 @@ for key, value in FEATURES.items():
         FEATURES[key] = True
 
 # Settings that will fail if we enable them, and we don't need them for docs anyway.
-FEATURES['RUN_AS_ANALYTICS_SERVER_ENABLED'] = False
-FEATURES['ENABLE_SOFTWARE_SECURE_FAKE'] = False
-FEATURES['ENABLE_MKTG_SITE'] = False
+FEATURES["RUN_AS_ANALYTICS_SERVER_ENABLED"] = False
+FEATURES["ENABLE_SOFTWARE_SECURE_FAKE"] = False
+FEATURES["ENABLE_MKTG_SITE"] = False
 
-INSTALLED_APPS.extend([
-    'cms.djangoapps.contentstore.apps.ContentstoreConfig',
-    'cms.djangoapps.course_creators',
-    'cms.djangoapps.xblock_config.apps.XBlockConfig',
-    'lms.djangoapps.lti_provider',
-])
+INSTALLED_APPS.extend(
+    [
+        "cms.djangoapps.contentstore.apps.ContentstoreConfig",
+        "cms.djangoapps.course_creators",
+        "cms.djangoapps.xblock_config.apps.XBlockConfig",
+        "lms.djangoapps.lti_provider",
+    ]
+)
+
+# Swagger generation details
+openapi_security_info_basic = (
+    "Obtain with a `POST` request to `/user/v1/account/login_session/`.  "
+    "If needed, copy the cookies from the response to your new call."
+)
+openapi_security_info_jwt = dedent(
+    """
+    Obtain by making a `POST` request to `/oauth2/v1/access_token`.
+
+    You will need to be logged in and have a client ID and secret already created.
+
+    Your request should have the headers
+
+    ```
+    'Content-Type': 'application/x-www-form-urlencoded'
+    ```
+
+    Your request should have the data payload
+
+    ```
+    'grant_type': 'client_credentials'
+    'client_id': [your client ID]
+    'client_secret':  [your client secret]
+    'token_type': 'jwt'
+    ```
+
+    Your JWT will be returned in the response as `access_token`. Prefix with `JWT ` in your header.
+    """
+)
+openapi_security_info_csrf = (
+    "Obtain by making a `GET` request to `/csrf/api/v1/token`. The token will be in the response cookie `csrftoken`."
+)
+SWAGGER_SETTINGS["SECURITY_DEFINITIONS"] = {
+    "Basic": {
+        "type": "basic",
+        "description": openapi_security_info_basic,
+    },
+    "jwt": {
+        "type": "apiKey",
+        "name": "Authorization",
+        "in": "header",
+        "description": openapi_security_info_jwt,
+    },
+    "csrf": {
+        "type": "apiKey",
+        "name": "X-CSRFToken",
+        "in": "header",
+        "description": openapi_security_info_csrf,
+    },
+}
 
 
-COMMON_TEST_DATA_ROOT = ''
+COMMON_TEST_DATA_ROOT = ""
 
 derive_settings(__name__)