WIP spectaculardevelop-5.0-spetacular

4 files changed, 45 insertions, 1 deletions

diff --git a/archaeological_operations/views_api.py b/archaeological_operations/views_api.py
index b6a17c837..3c66731e0 100644
--- a/archaeological_operations/views_api.py
+++ b/archaeological_operations/views_api.py
@@ -21,6 +21,27 @@ class ExportOperationAPI(ExportAPIView):
 
 class ExportSiteAPI(ExportAPIView):
     model = models.ArchaeologicalSite
+    @extend_schema(
+        # extra parameters added to the schema
+        parameters=[
+            OpenApiParameter(name='artist', description='Filter by artist', required=False, type=str),
+            OpenApiParameter(
+                name='release',
+                type=OpenApiTypes.DATE,
+                location=OpenApiParameter.QUERY,
+                description='Filter by release date',
+                examples=[
+                    OpenApiExample(
+                        'Example 1',
+                        summary='short optional summary',
+                        description='longer description',
+                        value='1993-08-23'
+                    ),
+                    ...
+                ],
+            ),
+        ],
+    )
 
 
 class GetOperationAPI(GetAPIView):
diff --git a/example_project/settings.py b/example_project/settings.py
index 709fce8ea..10e82aeee 100644
--- a/example_project/settings.py
+++ b/example_project/settings.py
@@ -308,6 +308,18 @@ JOINT = " | "
 # not managed cautiously the dir contening these scripts is not set by default
 ISHTAR_SCRIPT_DIR = ""
 
+# Open API schema configuration
+ISHTAR_OPENAPI = False  # allow to generate OpenAPI schema - usefull only for Ishtar editor
+REST_FRAMEWORK = {
+    # YOUR SETTINGS
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+}
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'Ishtar API',
+    'VERSION': get_version(),
+    'SERVE_INCLUDE_SCHEMA': False,
+}
+
 # GDPR
 GDPR_LOGGING = False
 GDPR_RETENTION_PERIOD = int(30.5 * 6) + 1  # ~ 6 month of logging
@@ -367,6 +379,10 @@ except ImportError:
 if USE_TRANSLATION_OVERLOAD:
     INSTALLED_APPS.insert(0, "overload_translation")
 
+if ISHTAR_OPENAPI:
+    INSTALLED_APPS.append("drf_spectacular")
+
+
 if "SECRET_KEY" not in globals():  # explicit import from the root for celery
     current_path = os.path.abspath(__file__)
     current_dir_path = os.path.dirname(current_path).split(os.sep)[-1]
diff --git a/ishtar_common/views_api.py b/ishtar_common/views_api.py
index 99ee48b41..e98a8f4fc 100644
--- a/ishtar_common/views_api.py
+++ b/ishtar_common/views_api.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python2
 # -*- coding: utf-8 -*-
 # Copyright (C) 2025 Étienne Loks  <etienne.loks at iggdrasil dot net>
 
@@ -30,6 +30,10 @@ from ishtar_common.models_imports import ImporterType, ImportChunk
 from ishtar_common.rest import GISAPIView
 from ishtar_common.views_item import get_item
 
+try:
+    from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiExample
+    from drf_spectacular.types import OpenApiTypes
+
 
 class ImporterTypeSerializer(serializers.ModelSerializer):
     model = serializers.SerializerMethodField()
diff --git a/requirements.txt b/requirements.txt
index 598ba1753..c05022bb1 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -95,3 +95,6 @@ django-guardian==2.4.0
 argon2-cffi==21.1.0
 cairosvg==2.5.2
 pathvalidate==2.5.2
+
+# optionnal - used to generate OpenAPI schema
+drf-spectacular==0.25.1