DRF spectacular OpenAPI schema generation fails

[stolpeo]

Problem

In VarFish, we use DRF spectacular to generate the OpenAPI schema. As VarFish is based on SODAR core, it iterates over the sources files as well. This causes an error and the API schema generation to fail.

Solution

Exclude the SODAR core files in VarFish for the DRF spectacular run.

Alternative Solutions

Change the API views in SODAR core.

Additional Context

The error stack looks as follows:

python3.11/site-packages/projectroles/serializers.py:148: Warning [ProjectCreateAPIView > ProjectSerializer > RoleAssignmentNestedListSerializer > SODARUserSerializer]: unable to resolve type hint for function "get_additional_emails". Consider using a type hint or @extend_schema_field. Defaulting to string.
python3.11/site-packages/projectroles/views_api.py:885: Error [ProjectInviteResendAPIView]: unable to guess serializer. This is graceful fallback handling for APIViews. Consider using GenericAPIView as view base class, if view is under your control. Either way you may want to add a serializer_class (or method). Ignoring view for now.
python3.11/site-packages/projectroles/views_api.py:850: Error [ProjectInviteRevokeAPIView]: unable to guess serializer. This is graceful fallback handling for APIViews. Consider using GenericAPIView as view base class, if view is under your control. Either way you may want to add a serializer_class (or method). Ignoring view for now.
python3.11/site-packages/projectroles/views_api.py:1375: Error [RemoteProjectGetAPIView]: unable to guess serializer. This is graceful fallback handling for APIViews. Consider using GenericAPIView as view base class, if view is under your control. Either way you may want to add a serializer_class (or method). Ignoring view for now.
python3.11/site-packages/projectroles/views_api.py:677: Error [RoleAssignmentOwnerTransferAPIView]: unable to guess serializer. This is graceful fallback handling for APIViews. Consider using GenericAPIView as view base class, if view is under your control. Either way you may want to add a serializer_class (or method). Ignoring view for now.
Traceback (most recent call last):
  File "/home/stolpeo/dev/varfish-server/backend/manage.py", line 29, in <module>
    execute_from_command_line(sys.argv)
  File "python3.11/site-packages/django/core/management/__init__.py", line 442, in execute_from_command_line
    utility.execute()
  File "python3.11/site-packages/django/core/management/__init__.py", line 436, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "python3.11/site-packages/django/core/management/base.py", line 412, in run_from_argv
    self.execute(*args, **cmd_options)
  File "python3.11/site-packages/django/core/management/base.py", line 458, in execute
    output = self.handle(*args, **options)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "python3.11/site-packages/drf_spectacular/management/commands/spectacular.py", line 72, in handle
    schema = generator.get_schema(request=None, public=True)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "python3.11/site-packages/drf_spectacular/generators.py", line 285, in get_schema
    paths=self.parse(request, public),
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "python3.11/site-packages/drf_spectacular/generators.py", line 250, in parse
    assert isinstance(view.schema, AutoSchema), (
AssertionError: Incompatible AutoSchema used on View <class 'projectroles.views_api.ProjectSettingRetrieveAPIView'>. Is DRF's DEFAULT_SCHEMA_CLASS pointing to "drf_spectacular.openapi.AutoSchema" or any other drf-spectacular compatible AutoSchema?

[mikkonie]

There seem to be quite a few errors, I'll try to address these in v1.0.3.

Initial thoughts:

• The type hint warning seems easily fixable with @extend_schema_view. Type hints will eventually be a thing across the repo (see Implement type annotations #1461), but not right now.
• Those "unable to guess serializer" errors seem to concern views which do not in fact have a serializer. Maybe there is some way I can tell that in the schema.
• Not sure about the "incompatible AutoSchema" one, maybe I have made some mistake in initializing this. generateschema didn't complain about any of these.

Installation docs for drf-spectacular here

[mikkonie]

It turns out the options are to either:

1. Install drf-spectacular in this repo and use its own decorators to update the views into not causing errors, OR
2. Ignore SODAR Core API views in the other project's schema creation

For now, we went with option 2 in Varfish. There is a separate ticket for adding drf-spectacular support in SODAR Core v1.1, see #1508.

Closing this issue.