[Fixes #14201] Dropped spectacular, replaced with docstrings for API endpoints

[giohappy]

No description provided.

[gemini-code-assist]

Code Review

This pull request removes the drf-spectacular dependency and its associated @extend_schema decorators across the GeoNode API views, transitioning documentation descriptions into method docstrings. The feedback identifies an incorrect docstring for the favorite method and recommends explicitly defining serializer_class within @action decorators for several endpoints to ensure that the built-in Django Rest Framework schema generator continues to produce accurate API documentation in the absence of drf-spectacular.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.65%. Comparing base (0343f6f) to head (db84d66).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #14202      +/-   ##
==========================================
+ Coverage   64.87%   74.65%   +9.78%     
==========================================
  Files         960      960              
  Lines       58866    58825      -41     
  Branches     8070     8018      -52     
==========================================
+ Hits        38188    43916    +5728     
+ Misses      19054    13108    -5946     
- Partials     1624     1801     +177     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[t-book]

Thanks @giohappy what do you plan regarding the amount of information the docstrings should provide?
Currently those read like minimal placeholders.

For example instead of

def members(self, request, pk=None):
    """API endpoint allowing to retrieve the Group members."""

We could do

 def members(self, request, pk=None):
    """
    Retrieve all members of a group.
    
    Args:
        request: HTTP request
        pk: Group ID
        
    Query Parameters:
        - page: Page number (default: 1)
        - page_size: Results per page (default: 20)
        
    Returns:
        200: Paginated list of UserSerializer objects
        404: Group not found
        403: User lacks permission to view group members
    """   

could be

def members(self, request, pk=None):
    """
    Retrieve group members.
    
    Permissions:
        - IsAuthenticated: User must be logged in
        - ViewGroup: User must have group view permission
    """

also decorators (IsAuthenticated…) return scodes and api version might be good?

And are you planning to use DRF's built-in include_docs_urls(), or another tool like to render these docstrings?

[giohappy]

@t-book, this is only the first cleanup step. I kept the descriptions from the spectacular decorators just for memory and as a basis for any solution we will decide.

Personally, I don't have a plan yet for an alternative autodoc solution. The many customisations inside serializers, mixins, custom responses, and the presence of dynamic filters, make any solution fail somewhere...

I suspect that, whatever we choose, it will need some manual tweaking.