Render OpenAPI Schema with Swagger UI

[Abh1ramManugur1]

Closes #418

Incorporated new drf-spectacular module to render OpenAPI Spec, as a result new nested serializers had to be added to serializers.py

Extended schema to incorporate view functions not automatically caught by drf-spectacular, excluded transient get legacy endpoint

[manning-ncsa]

This looks great so far! I'm experimenting with the interactive feature. By copying the sessionId from the auth cookie, I was able to interactively query and create an Alias object. I also verified that it appears on the transient result page.

[manning-ncsa]

Please use a code linter like flake8 and autopep8 in your IDE so we don't have to make commits like cfb5d4e.

[manning-ncsa]

Are the new serializer functions like CutoutNestedSerializer independent of the originals like CutoutSerializer used by the /api/[object] endpoints? We need to ensure if possible that there is only one serializer defined per model because otherwise we risk a divergence between the OpenAPI spec and the actual API responses.

[Abh1ramManugur1]

They are independent. I introduced the nested serializers to address warnings with the drf-spectacular module that were occurring due to the default name for nested serializers simply being 'NestedSerializer' leading to conflict and incorrect output on swagger-ui. That being said these aren't strictly necessary, as without them swagger ui would not display nested serializers properly which may be acceptable for our usage of it.

[manning-ncsa]

If I checkout commit cfb5d4e and then revert app/api/serializers.py to the main version, I see the errors listed below when exporting the OpenAPI using the new /api/schema/ endpoint. Posting here for future reference.

We need to carefully review these messages and improve the API itself based on them. For example, the messages related to Alias result from the /api/alias/ endpoints being poorly designed and implemented.

@Abh1ramManugur1 until we have a chance to carefully analyze these Nested classes, this will need to stay in draft mode.

1. /app/api/serializers.py: Warning [AliasViewSet > AliasSerializer]: unable to resolve type hint for function "get_transient". Consider using a type hint or @extend_schema_field. Defaulting to string.

2. /app/api/serializers.py: Warning [AliasViewSet > AliasSerializer]: unable to resolve type hint for function "get_host". Consider using a type hint or @extend_schema_field. Defaulting to string.

3. /usr/local/lib/python3.11/site-packages/rest_framework/serializers.py: Warning [ApertureViewSet > ApertureSerializer > NestedSerializer]: Encountered 2 components with identical names "Nested" and different identities <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'> and <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'>. This will very likely result in an incorrect schema. Try renaming one.

4. /usr/local/lib/python3.11/site-packages/rest_framework/serializers.py: Warning [AperturePhotometryViewSet > AperturePhotometrySerializer > NestedSerializer]: Encountered 2 components with identical names "Nested" and different identities <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'> and <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'>. This will very likely result in an incorrect schema. Try renaming one.

5. /usr/local/lib/python3.11/site-packages/rest_framework/serializers.py: Warning [CutoutViewSet > CutoutSerializer > NestedSerializer]: Encountered 2 components with identical names "Nested" and different identities <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'> and <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'>. This will very likely result in an incorrect schema. Try renaming one.

6. /app/api/serializers.py: Warning [HostViewSet > HostSerializer]: unable to resolve type hint for function "get_aliases". Consider using a type hint or @extend_schema_field. Defaulting to string.

7. /usr/local/lib/python3.11/site-packages/rest_framework/serializers.py: Warning [SEDFittingResultViewSet > SEDFittingResultSerializer > NestedSerializer]: Encountered 2 components with identical names "Nested" and different identities <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'> and <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'>. This will very likely result in an incorrect schema. Try renaming one.

8. /usr/local/lib/python3.11/site-packages/rest_framework/serializers.py: Warning [TaskRegisterViewSet > TaskRegisterSerializer > NestedSerializer]: Encountered 2 components with identical names "Nested" and different identities <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'> and <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'>. This will very likely result in an incorrect schema. Try renaming one.

9. /app/api/serializers.py: Warning [TransientViewSet > TransientSerializer]: unable to resolve type hint for function "get_aliases". Consider using a type hint or @extend_schema_field. Defaulting to string.

10. /usr/local/lib/python3.11/site-packages/rest_framework/serializers.py: Warning [TransientViewSet > TransientSerializer > NestedSerializer]: Encountered 2 components with identical names "Nested" and different identities <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'> and <class 'rest_framework.serializers.ModelSerializer.build_nested_field.<locals>.NestedSerializer'>. This will very likely result in an incorrect schema. Try renaming one.

11. /app/api/views.py: Error [get_transient_science_payload]: 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.

12. Warning: operationId "alias_retrieve" has collisions [('/api/alias/{alias}/', 'get'), ('/api/alias/{alias}/{object_type}/{name}/', 'get'), ('/api/alias/{id}/', 'get')]. resolving with numeral suffixes.

13. Warning: operationId "alias_create" has collisions [('/api/alias/{alias}/', 'post'), ('/api/alias/{alias}/{object_type}/{name}/', 'post')]. resolving with numeral suffixes.

14. Warning: operationId "alias_destroy" has collisions [('/api/alias/{alias}/', 'delete'), ('/api/alias/{alias}/{object_type}/{name}/', 'delete')]. resolving with numeral suffixes.