From 733b249643c94e494b197123c4a27b2dc1aeb219 Mon Sep 17 00:00:00 2001
From: Egor fureunoir Gorbunov <contact@fureunoir.com>
Date: Mon, 18 Aug 2025 15:02:57 +0300
Subject: [PATCH] Features: 1) Add `seo` endpoint to category schema for SEO
 metadata snapshots; 2) Add `seo` endpoint to product schema for SEO metadata
 snapshots; 3) Add `description` attribute to various endpoint schemas for
 enhanced documentation;

Fixes: 1) Remove redundant `seo` action mapping in `EvibesPermission`;

Extra: 1) Add missing import for `SeoSnapshotSerializer`; 2) Minor schema formatting improvements;
---
 core/docs/drf/viewsets.py | 46 +++++++++++++++++++++++++++++++++++++++
 core/permissions.py       |  1 -
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/core/docs/drf/viewsets.py b/core/docs/drf/viewsets.py
index 6a2dbfd1..2eeead63 100644
--- a/core/docs/drf/viewsets.py
+++ b/core/docs/drf/viewsets.py
@@ -35,6 +35,7 @@ from core.serializers import (
     WishlistDetailSerializer,
     WishlistSimpleSerializer,
 )
+from core.serializers.seo import SeoSnapshotSerializer
 from core.serializers.utility import AddressCreateSerializer, AddressSuggestionSerializer, DoFeedbackSerializer
 from payments.serializers import TransactionProcessSerializer
 
@@ -122,28 +123,50 @@ ATTRIBUTE_VALUE_SCHEMA = {
 CATEGORY_SCHEMA = {
     "list": extend_schema(
         summary=_("list all categories (simple view)"),
+        description=_("list all categories (simple view)"),
         responses={status.HTTP_200_OK: CategorySimpleSerializer(many=True), **BASE_ERRORS},
     ),
     "retrieve": extend_schema(
         summary=_("retrieve a single category (detailed view)"),
+        description=_("retrieve a single category (detailed view)"),
         responses={status.HTTP_200_OK: CategoryDetailSerializer(), **BASE_ERRORS},
     ),
     "create": extend_schema(
         summary=_("create a category"),
+        description=_("create a category"),
         responses={status.HTTP_201_CREATED: CategoryDetailSerializer(), **BASE_ERRORS},
     ),
     "destroy": extend_schema(
         summary=_("delete a category"),
+        description=_("delete a category"),
         responses={status.HTTP_204_NO_CONTENT: {}, **BASE_ERRORS},
     ),
     "update": extend_schema(
         summary=_("rewrite an existing category saving non-editables"),
+        description=_("rewrite an existing category saving non-editables"),
         responses={status.HTTP_200_OK: CategoryDetailSerializer(), **BASE_ERRORS},
     ),
     "partial_update": extend_schema(
         summary=_("rewrite some fields of an existing category saving non-editables"),
+        description=_("rewrite some fields of an existing category saving non-editables"),
         responses={status.HTTP_200_OK: CategoryDetailSerializer(), **BASE_ERRORS},
     ),
+    "seo": extend_schema(
+        summary=_("SEO Meta Snapshot"),
+        description=_("returns a snapshot of the category's SEO meta data"),
+        parameters=[
+            OpenApiParameter(
+                name="lookup",
+                location="path",
+                description=_("Category UUID or slug"),
+                type=str,
+            ),
+        ],
+        responses={
+            status.HTTP_200_OK: SeoSnapshotSerializer(),
+            **BASE_ERRORS,
+        },
+    ),
 }
 
 ORDER_SCHEMA = {
@@ -347,6 +370,7 @@ ATTRIBUTES_DESC = _(
 PRODUCT_SCHEMA = {
     "list": extend_schema(
         summary=_("list all products (simple view)"),
+        description=_("list all products (simple view)"),
         parameters=[
             OpenApiParameter(
                 name="uuid",
@@ -439,6 +463,7 @@ PRODUCT_SCHEMA = {
     ),
     "retrieve": extend_schema(
         summary=_("retrieve a single product (detailed view)"),
+        description=_("retrieve a single product (detailed view)"),
         parameters=[
             OpenApiParameter(
                 name="lookup_value",
@@ -454,6 +479,7 @@ PRODUCT_SCHEMA = {
     ),
     "create": extend_schema(
         summary=_("create a product"),
+        description=_("create a product"),
         responses={
             status.HTTP_201_CREATED: ProductDetailSerializer(),
             **BASE_ERRORS,
@@ -461,6 +487,7 @@ PRODUCT_SCHEMA = {
     ),
     "update": extend_schema(
         summary=_("rewrite an existing product, preserving non-editable fields"),
+        description=_("rewrite an existing product, preserving non-editable fields"),
         parameters=[
             OpenApiParameter(
                 name="lookup",
@@ -476,6 +503,7 @@ PRODUCT_SCHEMA = {
     ),
     "partial_update": extend_schema(
         summary=_("update some fields of an existing product, preserving non-editable fields"),
+        description=_("update some fields of an existing product, preserving non-editable fields"),
         parameters=[
             OpenApiParameter(
                 name="lookup",
@@ -491,6 +519,7 @@ PRODUCT_SCHEMA = {
     ),
     "destroy": extend_schema(
         summary=_("delete a product"),
+        description=_("delete a product"),
         parameters=[
             OpenApiParameter(
                 name="lookup",
@@ -506,6 +535,7 @@ PRODUCT_SCHEMA = {
     ),
     "feedbacks": extend_schema(
         summary=_("lists all permitted feedbacks for a product"),
+        description=_("lists all permitted feedbacks for a product"),
         parameters=[
             OpenApiParameter(
                 name="lookup",
@@ -519,6 +549,22 @@ PRODUCT_SCHEMA = {
             **BASE_ERRORS,
         },
     ),
+    "seo": extend_schema(
+        summary=_("SEO Meta Snapshot"),
+        description=_("returns a snapshot of the product's SEO meta data"),
+        parameters=[
+            OpenApiParameter(
+                name="lookup",
+                location="path",
+                description=_("Product UUID or slug"),
+                type=str,
+            ),
+        ],
+        responses={
+            status.HTTP_200_OK: SeoSnapshotSerializer(),
+            **BASE_ERRORS,
+        },
+    ),
 }
 
 ADDRESS_SCHEMA = {
diff --git a/core/permissions.py b/core/permissions.py
index 69230b3d..a462229b 100644
--- a/core/permissions.py
+++ b/core/permissions.py
@@ -17,7 +17,6 @@ class IsOwnerOrReadOnly(permissions.BasePermission):
 class EvibesPermission(permissions.BasePermission):
     ACTION_PERM_MAP = {
         "retrieve": "view",
-        "seo": "view",
         "list": "view",
         "create": "add",
         "update": "change",