Improve docs for get params Django API

Author: TheSuperiorStanislav

CHANGELOG.md

@@ -6,6 +6,7 @@ We follow [Semantic Versions](https://semver.org/).
 
 - Replace [httpx](https://github.com/encode/httpx) with
 [httpx2](https://github.com/pydantic/httpx2) in docs and tests
+- Improve docs for get params Django API
 
 ## 0.8.0
 

pyproject.toml

@@ -108,6 +108,10 @@ local = [
   # A library and CLI app for rendering project templates.
   # https://copier.readthedocs.io/en/latest/
   "copier",
+  # Werkzeug is a comprehensive WSGI web application library.
+  # Required to use runserver_plus
+  # https://werkzeug.palletsprojects.com/en/stable/
+  "Werkzeug",
 ]
 linters = [
   # Mypy is a static type checker for Python.

saritasa_s3_tools/configs.py

@@ -39,6 +39,32 @@ class S3FileTypeConfig(metaclass=S3FileTypeConfigMeta):
     expires_in: int = 3600
     success_action_status: int = 201
     # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
-    content_disposition: (
-        typing.Literal["attachment"] | typing.Literal["inline"]
-    ) = "attachment"
+    content_disposition: typing.Literal["attachment", "inline"] = "attachment"
+
+    @staticmethod
+    def get_formatted_s3_configs() -> str:
+        """Get formatted S3 configs descriptions for api description."""
+        formatted_s3_configs: list[str] = []
+        for name, config in S3FileTypeConfig.configs.items():
+            allowed_types = (
+                ", ".join(config.allowed) if config.allowed else "All types"
+            )
+            content_length_range = (
+                (
+                    f"{config.content_length_range[0]}-"
+                    f"{config.content_length_range[1]} bytes"
+                )
+                if config.content_length_range
+                else "Any length"
+            )
+            formatted_s3_configs.append(
+                f"`{name}`\n\n"
+                f"| Parameter | Value |\n"
+                f"|:---|:---|\n"
+                f"| Allowed | {allowed_types} |\n"
+                f"| Content length range | {content_length_range} |\n"
+                f"| Expires in | {config.expires_in} seconds |\n"
+                f"| Success action status | {config.success_action_status} |\n"
+                f"| Content disposition | {config.content_disposition} |",
+            )
+        return "\n\n".join(formatted_s3_configs)

saritasa_s3_tools/django/views.py

@@ -154,3 +154,21 @@ def get_extra_meta_data(
             responses=serializers.S3ConfigSerializer(),
         ),
     )(S3GetParamsView)
+
+
+class _Docs(str):
+    """Hack to make dynamic docs for drf-spectacular."""
+
+    def expandtabs(
+        self,
+        *args: typing.Any,
+        **kwargs,
+    ) -> str:
+        return str(
+            self
+            + "\n\n**Available configs**:\n\n"
+            + configs.S3FileTypeConfig.get_formatted_s3_configs(),
+        ).expandtabs(*args, **kwargs)
+
+
+S3GetParamsView.get_params.__doc__ = _Docs(S3GetParamsView.get_params.__doc__)