add drf-spectacular support, fix api views (wip) (#1508)

.github/ISSUE_TEMPLATE/release_cleanup.md

@@ -27,7 +27,7 @@ TBA
 - [ ] Update version number and date in `CHANGELOG`
 - [ ] Update version number and date in `Major Changes` doc
 - [ ] Ensure docs can be built without errors
-- [ ] Ensure `generateschema` runs without errors or warnings (until in CI)
+- [ ] Ensure `make spectacular` runs without errors or warnings (until in CI)
 
 ## Notes
 

CHANGELOG.rst

@@ -11,6 +11,8 @@ Unreleased
 Added
 -----
 
+- **General**
+    - ``drf-spectacular`` support (#1508)
 - **Projectroles**
     - ``SODARUser.get_display_name()`` helper (#1487)
     - App setting type constants (#1458)
@@ -104,6 +106,7 @@ Removed
 
 - **General**
     - Migrations squashed in v1.0 (#1455)
+    - DRF ``generateschema`` support (#1508)
 - **Projectroles**
     - Support for deprecated search results as dict (#1400)
     - Support for deprecated app setting ``local`` parameter (#1394)

Makefile

@@ -11,6 +11,7 @@ define USAGE=
 @echo -e "\tmake collectstatic                       -- run collectstatic"
 @echo -e "\tmake test [arg=<test_object>]            -- run all tests or specify module/class/function"
 @echo -e "\tmake manage_target arg=<target_command>  -- run management command on target site, arg is mandatory"
+@echo -e "\tmake spectacular                         -- generate API documentation with drf-spectacular"
 @echo -e
 endef
 
@@ -67,6 +68,11 @@ else
 endif
 
 
+.PHONY: spectacular
+spectacular:
+	$(MANAGE) spectacular --color $(arg)
+
+
 .PHONY: usage
 usage:
 	$(USAGE)

config/settings/base.py

@@ -68,6 +68,7 @@
     'dal',  # For user search combo box
     'dal_select2',
     'dj_iconify.apps.DjIconifyConfig',  # Iconify for SVG icons
+    'drf_spectacular',  # OpenAPI schema generation
 ]
 
 # Project apps
@@ -332,7 +333,6 @@
 # Django REST framework
 # ------------------------------------------------------------------------------
 
-
 REST_FRAMEWORK = {
     'DEFAULT_AUTHENTICATION_CLASSES': (
         'rest_framework.authentication.BasicAuthentication',
@@ -343,8 +343,10 @@
         'rest_framework.pagination.PageNumberPagination'
     ),
     'PAGE_SIZE': SODAR_API_PAGE_SIZE,
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
 }
 
+
 # Additional authentication settings
 # ------------------------------------------------------------------------------
 

docs/source/major_changes.rst

@@ -24,6 +24,7 @@ Release Highlights
 - Add app setting type constants
 - Add app setting definition as objects
 - Add API view to retrieve user details by user UUID
+- Add drf-spectacular support for API documentation
 - Update project list for flat list display
 - Update owner transfer form to allow setting no role for old owner
 - Update app settings API
@@ -37,6 +38,7 @@ Release Highlights
 - Remove support for sodarcache REST API <v2.0
 - Remove support for timeline REST API <v2.0
 - Remove support for SODAR Core features deprecated in v1.0
+- Remove support for generateschema
 - Remove squashed migrations
 
 Breaking Changes
@@ -157,6 +159,13 @@ App Settings Local Attribute
     ``local`` attribute is no longer supported. Instead, access the
     ``global_edit`` member of a ``PluginAppSettingDef`` object directly.
 
+DRF-Spectacular Used for OpenAPI Schemas
+----------------------------------------
+
+This release adds support for ``drf-spectacular`` to generate OpenAPI schemas.
+Use ``make spectacular`` to generate your schemas. Support for the DRF default
+``generateschema`` command has been removed.
+
 Squashed Migrations Removed
 ---------------------------
 

requirements/base.txt

@@ -85,3 +85,6 @@ celery>=5.4.0, <5.5
 
 # Django autocomplete light (DAL)
 django-autocomplete-light==3.11.0
+
+# DRF-spectacular for OpenAPI schema generation
+drf-spectacular>=0.28.0, <0.29

sodarcache/tests/test_views_api.py

@@ -249,6 +249,7 @@ def test_post_create(self):
         response = self.request_knox(url, method='POST', data=post_data)
 
         self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data, {'detail': 'ok'})
         self.assertEqual(JSONCacheItem.objects.all().count(), 2)
         item = JSONCacheItem.objects.get(name='new_test_item')
         expected = {
@@ -277,6 +278,7 @@ def test_post_update(self):
         response = self.request_knox(url, method='POST', data=post_data)
 
         self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data, {'detail': 'ok'})
         self.assertEqual(JSONCacheItem.objects.all().count(), 1)
         item = JSONCacheItem.objects.get(name=ITEM_NAME)
         expected = {

sodarcache/views_api.py

@@ -1,12 +1,15 @@
 """REST API views for the sodarcache app"""
 
+from rest_framework import serializers
 from rest_framework.exceptions import APIException, NotFound, ParseError
 from rest_framework.generics import RetrieveAPIView
 from rest_framework.renderers import JSONRenderer
 from rest_framework.response import Response
 from rest_framework.versioning import AcceptHeaderVersioning
 from rest_framework.views import APIView
 
+from drf_spectacular.utils import extend_schema, inline_serializer
+
 # Projectroles dependency
 from projectroles.models import SODAR_CONSTANTS
 from projectroles.plugins import get_backend_api
@@ -113,6 +116,14 @@ def get_object(self):
         return item
 
 
+@extend_schema(
+    responses={
+        '200': inline_serializer(
+            'UpdateTimeResponse',
+            fields={'update_time': serializers.IntegerField()},
+        )
+    }
+)
 class CacheItemDateRetrieveAPIView(
     SodarcacheAPIViewMixin, SODARAPIGenericProjectMixin, APIView
 ):
@@ -165,9 +176,10 @@ class CacheItemSetAPIView(
     - ``data``: Full item data to be set (JSON)
     """
 
+    http_method_names = ['post']
     permission_required = 'sodarcache.set_cache_value'
     project_type = PROJECT_TYPE_PROJECT
-    http_method_names = ['post']
+    serializer_class = JSONCacheItemSerializer
 
     def post(self, request, *args, **kwargs):
         cache_backend = self.get_backend()