Docs links for post, better set permissions schema

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.

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,

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,
         },
     ),
 )

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",
     },