Migration to drf_spectacular

[Marishka17]

Motivation and context

Resolves #3015
Resolves #2006

How has this been tested?

Checklist

• I submit my changes into the develop branch
• I have added a description of my changes into CHANGELOG file
  - [ ] I have updated the documentation accordingly
  - [ ] I have added tests to cover my changes
• I have linked related issues (read github docs)
  - [ ] I have increased versions of npm packages if it is necessary (cvat-canvas,
  cvat-core, cvat-data and cvat-ui)

License

• I submit my code changes under the same MIT License that covers the project.
  Feel free to contact the maintainers if that's a concern.
• I have updated the license header for each file (see an example below)

# Copyright (C) 2022 Intel Corporation
#
# SPDX-License-Identifier: MIT

[nmanovic]

@Marishka17 , I have a couple of questions:

• Is it possible to detect the current protocol automatically? (http or https)
• Is it possible to detect the server host and port automatically? Why do we need the choice?

[Marishka17]

@nmanovic, all comments have been fixed.

[nmanovic]

LGTM

[tfranzel]

Hey, I sometime look at big projects using spectacular to discover new usage patterns and possible bugs.

found quite a few unnecessarily complicated usages throughout. probably muscle-memory from yasg 😄 here are a few comments for improvement if you are interested. only commented each thing once but the patterns do repeat.

otherwise great PR, enjoy!

[tfranzel]

this is more complicated than it needs to be. following snippet generates exactly the same schema. some notes fyi:

• common annotations (tags) can be done once with @extend_schema on top.
• no point in overriding responses when it is just default behavior. in fact it's misleading since you use the automatic request estimation while overriding responses
• the version annotation is actually counter-productive because you are scoping the decorators. if someone could request 3.0, the default behavior would run, i.e. these decorators would be simply skipped. it's advisable to only "scope-decorate" non-DEFAULT_VERSION behavior.
• also the view does not make use of different versions anyway, thus the default behavior does exactly the right thing already.
• @extend_schema_view takes multiple args. no need for duplication

@extend_schema(tags=["organizations"])
@extend_schema_view(
    retrieve=extend_schema(
        summary="Method returns details of an organization"
    ),
    list=extend_schema(
        summary="Method returns a paginated list of organizatins according to query parameters"
    ),
    update=extend_schema(
        summary="Method updates an organization by id",
    ),
    partial_update=extend_schema(
        summary="Methods does a partial update of chosen fields in an organization",
    ),
    create=extend_schema(
        summary="Method creates an organization",
    ),
    destroy=extend_schema(
        summary="Method deletes an organization",
        responses={204: OpenApiResponse(description="The organization has been deleted")},
    ),
)
class OrganizationViewSet(viewsets.ModelViewSet):
   ....

[tfranzel]

• due to giving serializer_class=AboutSerializer, the serializer is detected automatically.
• 200 is the default code for actions (for native viewsets methods (list/retrieve/etc) 200, 201, 204 are detected automatically)

so this responses=... is not needed. spectacular gets this right automatically. you would only need it if many=True were used, like in some other places.

[tfranzel]

fyi: spectacular does support docstring extraction just the same as yasg.

this would only be useful if you wanted to split summary and description while keeping them close together.

[Marishka17]

@tfranzel, Hello!
Thanks for the comments! I will take them into account shortly in the next step of improving our schema.