add setting for manual path prefix: SCHEMA_PATH_PREFIX_INSERT #567

drf_spectacular/generators.py

@@ -241,6 +241,9 @@ def parse(self, input_request, public):
             if spectacular_settings.SCHEMA_PATH_PREFIX_TRIM:
                 path = re.sub(pattern=path_prefix, repl='', string=path, flags=re.IGNORECASE)
 
+            if spectacular_settings.SCHEMA_PATH_PREFIX_INSERT:
+                path = spectacular_settings.SCHEMA_PATH_PREFIX_INSERT + path
+
             if not path.startswith('/'):
                 path = '/' + path
 

drf_spectacular/settings.py

@@ -13,6 +13,12 @@
     # Remove matching SCHEMA_PATH_PREFIX from operation path. Usually used in
     # conjunction with appended prefixes in SERVERS.
     'SCHEMA_PATH_PREFIX_TRIM': False,
+    # Insert a manual path prefix to the operation path, e.g. '/service/backend'.
+    # Use this for example to align paths when the API is mounted as a sub-resource
+    # behind a proxy and Django is not aware of that. Alternatively, prefixes can
+    # also specified via SERVERS, but this makes the operation path more explicit.
+    'SCHEMA_PATH_PREFIX_INSERT': '',
+
 
     # Coercion of {pk} to {id} is controlled by SCHEMA_COERCE_PATH_PK. Additionally,
     # some libraries (e.g. drf-nested-routers) use "_pk" suffixed path variables.
@@ -89,6 +95,7 @@
     'SORT_OPERATIONS': True,
 
     # enum name overrides. dict with keys "YourEnum" and their choice values "field.choices"
+    # e.g. {'SomeEnum': ['A', 'B'], 'OtherEnum': 'import.path.to.choices'}
     'ENUM_NAME_OVERRIDES': {},
     # Adds "blank" and "null" enum choices where appropriate. disable on client generation issues
     'ENUM_ADD_EXPLICIT_BLANK_NULL_CHOICE': True,
@@ -151,6 +158,7 @@
     'VERSION': '0.0.0',
     # Optional list of servers.
     # Each entry MUST contain "url", MAY contain "description", "variables"
+    # e.g. [{'url': 'https://example.com/v1', 'description': 'Text'}, ...]
     'SERVERS': [],
     # Tags defined in the global scope
     'TAGS': [],

tests/test_regressions.py

@@ -2722,3 +2722,14 @@ def pi(request, format=None):
     else:
         assert get_request_schema(operation)['items'] == {'$ref': '#/components/schemas/XRequest'}
         assert get_response_schema(operation)['items'] == {'$ref': '#/components/schemas/X'}
+
+
+@mock.patch('drf_spectacular.settings.spectacular_settings.SCHEMA_PATH_PREFIX_INSERT', '/service/backend')
+def test_schema_path_prefix_insert(no_warnings):
+    @extend_schema(responses=typing.Any)
+    @api_view(['GET'])
+    def view_func(request, format=None):
+        pass  # pragma: no cover
+
+    schema = generate_schema('v1/x/', view_function=view_func)
+    assert '/service/backend/v1/x/' in schema['paths']