feat: add OpenAPI support for "preview" query parameter (#53)

* feat: add OpenAPI support for "preview" query parameter

* refactor: implement fallback for OpenAPI schema utilities in case of missing drf-spectacular

* fix: remove unused typing import `Callable` from views_base.py

* add `drf-spectacular` to test settings and requirements

* chore: fix missing libcairo support

Author: metaforx

.github/workflows/test.yml

@@ -25,6 +25,11 @@ jobs:
       uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Install system deps (cairo stack)
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          build-essential libcairo2-dev pkg-config python3-dev
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

djangocms_rest/views.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Callable, ParamSpec, TypeVar
 from django.contrib.sites.shortcuts import get_current_site
 from django.urls import reverse
 from django.utils.functional import lazy
@@ -32,26 +32,53 @@
 )
 from djangocms_rest.views_base import BaseAPIView, BaseListAPIView
 
+P = ParamSpec("P")
+T = TypeVar("T")
 
 try:
-    from drf_spectacular.types import OpenApiTypes  # noqa: F401
-    from drf_spectacular.utils import OpenApiParameter, extend_schema  # noqa: F401
+    from drf_spectacular.types import OpenApiTypes
+    from drf_spectacular.utils import OpenApiParameter, extend_schema
 
     extend_placeholder_schema = extend_schema(
         parameters=[
             OpenApiParameter(
                 name="html",
                 type=OpenApiTypes.INT,
-                location=OpenApiParameter.QUERY,
+                location="query",
                 description="Set to 1 to include HTML rendering in response",
                 required=False,
                 enum=[1],
+            ),
+            OpenApiParameter(
+                name="preview",
+                type=OpenApiTypes.BOOL,
+                location="query",
+                description="Set to true to preview unpublished content (admin access required)",
+                required=False,
             )
         ]
     )
-except ImportError:
 
-    def extend_placeholder_schema(func):
+except ImportError: # pragma: no cover
+    class OpenApiTypes:
+        BOOL = "boolean"
+        INT = "integer"
+
+    class OpenApiParameter:  # pragma: no cover
+        QUERY = "query"
+        PATH = "path"
+        HEADER = "header"
+        COOKIE = "cookie"
+
+        def __init__(self, *args, **kwargs):
+            pass
+
+    def extend_schema(*_args, **_kwargs):  # pragma: no cover
+        def _decorator(obj: T) -> T:
+            return obj
+        return _decorator
+
+    def extend_placeholder_schema(func: Callable[P, T]) -> Callable[P, T]:
         return func
 
 
@@ -60,7 +87,7 @@ def extend_placeholder_schema(func):
 # and keeps the code cleaner.
 # Attn: Dynamic changes to the plugin pool will not be reflected in the
 # plugin definitions.
-# If you need to update the plugin definitions, you need reassign the variable.
+# If you need to update the plugin definitions, you need to reassign the variable.
 PLUGIN_DEFINITIONS = lazy(
     PluginDefinitionSerializer.generate_plugin_definitions, dict
 )()

djangocms_rest/views_base.py

@@ -1,10 +1,51 @@
+from typing import ParamSpec, TypeVar
+
 from django.contrib.sites.shortcuts import get_current_site
 from django.utils.functional import cached_property
 from rest_framework.generics import ListAPIView
 from rest_framework.permissions import IsAdminUser
 from rest_framework.views import APIView
 
+P = ParamSpec("P")
+T = TypeVar("T")
+
+try:
+    from drf_spectacular.types import OpenApiTypes
+    from drf_spectacular.utils import OpenApiParameter, extend_schema
+
+    preview_schema = extend_schema(
+        parameters=[
+            OpenApiParameter(
+                name="preview",
+                type=OpenApiTypes.BOOL,
+                location="query",
+                description="Set to true to preview unpublished content (admin access required)",
+                required=False,
+            )
+        ]
+    )
+except ImportError: # pragma: no cover
+    class OpenApiTypes:
+        BOOL = "boolean"
+
+    class OpenApiParameter:  # pragma: no cover
+        QUERY = "query"
+        PATH = "path"
+        HEADER = "header"
+        COOKIE = "cookie"
+
+        def __init__(self, *args, **kwargs):
+            pass
+
+    def extend_schema(*_args, **_kwargs):  # pragma: no cover
+        def _decorator(obj: T) -> T:
+            return obj
+        return _decorator
+
+    def preview_schema(obj: T) -> T: # pragma: no cover
+        return obj
 
+@preview_schema
 class BaseAPIMixin:
     """
     This mixin provides common functionality for all API views.

tests/requirements/base.txt

@@ -4,6 +4,7 @@ djangocms-text
 django-filer
 beautifulsoup4
 setuptools
+drf-spectacular
 
 # other requirements
 coverage

tests/settings.py

@@ -34,6 +34,7 @@ def __getitem__(self, item):
     "tests.test_app",
     "filer",
     "easy_thumbnails",
+    "drf_spectacular",
 ]
 
 MIDDLEWARE = [