From 0aad777c3f32c5fe74b542c2889b5d76f8fe9dfb Mon Sep 17 00:00:00 2001
From: shamoon <4887959+shamoon@users.noreply.github.com>
Date: Sat, 30 Nov 2024 22:21:51 -0800
Subject: [PATCH] Docs links for post, better set permissions schema

---
 docs/api.md                  |  2 ++
 src/documents/serialisers.py | 39 +++++++++++++++++++++++++++++++++++-
 src/documents/views.py       |  8 ++++++--
 src/paperless/settings.py    |  4 ++++
 4 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 3cbb5d24e..82d9a71b6 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -4,6 +4,8 @@ Paperless-ngx now ships with a fully-documented REST API and a browsable
 web interface to explore it. The API browsable interface is available at
 `/api/api/schema/swagger-ui/`.
 
+Further documentation is provided here for some endpoints and features.
+
 ## Authorization
 
 The REST api provides four different forms of authentication.
diff --git a/src/documents/serialisers.py b/src/documents/serialisers.py
index 0e1084c0c..7239b9d48 100644
--- a/src/documents/serialisers.py
+++ b/src/documents/serialisers.py
@@ -184,6 +184,43 @@ class SerializerWithPerms(serializers.Serializer):
         super().__init__(*args, **kwargs)
 
 
+@extend_schema_field(
+    field={
+        "type": "object",
+        "properties": {
+            "view": {
+                "type": "object",
+                "properties": {
+                    "users": {
+                        "type": "array",
+                        "items": {"type": "integer"},
+                    },
+                    "groups": {
+                        "type": "array",
+                        "items": {"type": "integer"},
+                    },
+                },
+            },
+            "change": {
+                "type": "object",
+                "properties": {
+                    "users": {
+                        "type": "array",
+                        "items": {"type": "integer"},
+                    },
+                    "groups": {
+                        "type": "array",
+                        "items": {"type": "integer"},
+                    },
+                },
+            },
+        },
+    },
+)
+class SetPermissionsSerializer(serializers.DictField):
+    pass
+
+
 class OwnedObjectSerializer(
     SerializerWithPerms,
     serializers.ModelSerializer,
@@ -285,7 +322,7 @@ class OwnedObjectSerializer(
     user_can_change = SerializerMethodField(read_only=True)
     is_shared_by_requester = SerializerMethodField(read_only=True)
 
-    set_permissions = serializers.DictField(
+    set_permissions = SetPermissionsSerializer(
         label="Set permissions",
         allow_empty=True,
         required=False,
diff --git a/src/documents/views.py b/src/documents/views.py
index 751048b2a..d607d83bc 100644
--- a/src/documents/views.py
+++ b/src/documents/views.py
@@ -1309,10 +1309,14 @@ class BulkEditView(PassUserMixin):
 
 
 @extend_schema_view(
-    get=extend_schema(
+    post=extend_schema(
         description="Upload a document via the API",
+        external_docs={
+            "description": "Further documentation",
+            "url": "https://docs.paperless-ngx.com/api/#file-uploads",
+        },
         responses={
-            (200, "application/json"): serializers.CharField(),
+            (200, "application/json"): OpenApiTypes.STR,
         },
     ),
 )
diff --git a/src/paperless/settings.py b/src/paperless/settings.py
index 916306aff..a0f006464 100644
--- a/src/paperless/settings.py
+++ b/src/paperless/settings.py
@@ -359,6 +359,10 @@ SPECTACULAR_SETTINGS = {
     "SERVE_INCLUDE_SCHEMA": False,
     "SWAGGER_UI_DIST": "SIDECAR",
     "COMPONENT_SPLIT_REQUEST": True,
+    "EXTERNAL_DOCS": {
+        "description": "Paperless-ngx API Documentation",
+        "url": "https://docs.paperless-ngx.com/api/",
+    },
     "ENUM_NAME_OVERRIDES": {
         "MatchingAlgorithm": "documents.models.MatchingModel.MATCHING_ALGORITHMS",
     },