[SDESK-7487] Add docstrings about usage of url in endpoints

superdesk/core/resources/resource_rest_endpoints.py

@@ -9,8 +9,7 @@
 # at https://www.sourcefabric.org/superdesk/license
 
 import math
-from inspect import get_annotations
-from typing import Annotated, List, Optional, cast, Dict, Any, Type, get_args, get_origin
+from typing import List, Optional, cast, Dict, Any, Type
 
 from dataclasses import dataclass
 from pydantic import ValidationError, BaseModel, NonNegativeInt
@@ -20,7 +19,9 @@
 from bson import ObjectId
 
 from superdesk.core import json
-from superdesk.core.app import get_app_config, get_current_async_app
+from superdesk.utils import get_cors_headers
+from superdesk.errors import SuperdeskApiError
+from superdesk.core.app import get_current_async_app
 from superdesk.core.types import (
     SearchRequest,
     SearchArgs,
@@ -31,14 +32,12 @@
     Response,
     RestGetResponse,
 )
-from superdesk.errors import SuperdeskApiError
 from superdesk.resource_fields import STATUS, STATUS_OK, ITEMS
 from superdesk.core.web import RestEndpoints, ItemRequestViewArgs, Endpoint
-from superdesk.utils import get_cors_headers, join_url_parts
 
 from .model import ResourceModel
 from .resource_config import ResourceConfig
-from .validators import AsyncValidator, convert_pydantic_validation_error_for_response
+from .validators import convert_pydantic_validation_error_for_response
 
 
 @dataclass

superdesk/core/types/search.py

@@ -54,6 +54,7 @@ class SearchArgs(TypedDict, total=False):
     filters: list[dict[str, Any]]
 
     #: A JSON string containing the field projections to filter out the returned fields
+    # Kept for compatibility with python-eve. Use `SearchRequest.projection` preferably.
     projections: str
 
     version: VersionParam | None

superdesk/core/types/web.py

@@ -222,6 +222,11 @@ class Endpoint:
     """Base class used for registering and processing endpoints"""
 
     #: URL for the endpoint
+    #: If the URL starts with "/", it will be used as-is.
+    #: Otherwise, the API prefix will be prepended to the URL.
+    #: For example:
+    #: - "items" -> "{api_prefix}{api_version}/items"
+    #: - "/custom/path" -> "/custom/path"
     url: str
 
     #: Name of the endpoint (must be unique)

superdesk/core/web/endpoints.py

@@ -163,12 +163,16 @@ def __call__(self, args: dict[str, Any], params: dict[str, Any], request: Reques
 
 def endpoint(url: str, name: str | None = None, methods: list[HTTP_METHOD] | None = None, auth: AuthConfig = None):
     """Decorator function to convert a pure function to an Endpoint instance
-
-    This is then later used to register with a Module or the app.
-
-    :param url: The URL of the endpoint
-    :param name: The optional name of the endpoint
-    :param methods: The optional list of HTTP methods allowed
+    which is later used to register with a Module or the app.
+
+    Args:
+        url: The URL of the endpoint. If it starts with "/", it will be used exactly as provided.
+            Otherwise, the API prefix and version will be automatically prepended.
+            For example:
+            - "items" becomes "{api_prefix}{api_version}/items"
+            - "/custom/path" stays as "/custom/path"
+        name: The optional name of the endpoint
+        methods: The optional list of HTTP methods allowed
     """
 
     def convert_to_endpoint(func: EndpointFunction):