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

@@ -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 = {

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