Dovodi_Backend/apps/hadis/doc.py

"""
Swagger documentation for the Hadis API endpoints.

This module provides Swagger documentation for the Hadis API endpoints using drf-yasg.
It defines the request parameters, response schemas, and decorators for the views.
"""

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

from apps.hadis.models import HadisCategory

# Parameter definitions
source_type_param = openapi.Parameter(
    'source_type',
    openapi.IN_QUERY,
    description="Filter categories by source type (shia or sunni)",
    type=openapi.TYPE_STRING,
    enum=[HadisCategory.SourceType.SHIA, HadisCategory.SourceType.SUNNI],
    required=False
)

# Response schemas
tag_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the tag"
        ),
        'title': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Title of the tag"
        )
    },
    required=['id', 'title']
)

category_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the category"
        ),
        'name': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Name of the category"
        ),
        'hadis_count': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Number of hadis items in this category"
        ),
        'source_type': openapi.Schema(
            type=openapi.TYPE_STRING,
            enum=[HadisCategory.SourceType.SHIA, HadisCategory.SourceType.SUNNI],
            description="Source type of the category (shia or sunni)"
        ),
        'category_type': openapi.Schema(
            type=openapi.TYPE_STRING,
            enum=[HadisCategory.ContentType.QURAN, HadisCategory.ContentType.HADITH],
            description="Content type of the category (quran or hadith)",
            nullable=True
        ),
        'children': openapi.Schema(
            type=openapi.TYPE_ARRAY,
            items=openapi.Schema(type=openapi.TYPE_OBJECT),  # Recursive reference
            description="List of child categories"
        )
    },
    required=['id', 'name', 'hadis_count', 'source_type', 'children']
)

categories_response = openapi.Response(
    description="Tree structure of hadis categories",
    schema=openapi.Schema(
        type=openapi.TYPE_ARRAY,
        items=category_schema
    )
)

hadis_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'number': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique number identifier for the hadis"
        ),
        'title': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Title of the hadis"
        ),
        'text': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Original text of the hadis"
        ),
        'translation': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Translation of the hadis text"
        ),
        'tags': openapi.Schema(
            type=openapi.TYPE_ARRAY,
            items=tag_schema,
            description="List of tags associated with this hadis"
        )
    },
    required=['number', 'title', 'text', 'translation', 'tags']
)

hadis_list_response = openapi.Response(
    description="List of hadis items in the specified category",
    schema=openapi.Schema(
        type=openapi.TYPE_ARRAY,
        items=hadis_schema
    )
)

# Reference image schema
reference_image_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the reference image"
        ),
        'thumbnail': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="ID of the thumbnail image",
            nullable=True
        ),
        'priority': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Priority of the image (lower values mean higher priority)"
        )
    },
    required=['id', 'priority']
)

# Hadis reference schema
hadis_reference_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the hadis reference"
        ),
        'book': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="ID of the referenced book",
            nullable=True
        ),
        'description': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Description of the reference",
            nullable=True
        ),
        'created_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Creation timestamp"
        ),
        'images': openapi.Schema(
            type=openapi.TYPE_ARRAY,
            items=reference_image_schema,
            description="List of reference images"
        )
    },
    required=['id', 'created_at', 'images']
)

# Hadis overview schema
hadis_overview_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'status': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Status of the hadis"
        ),
        'status_color': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Display color for the status"
        ),
        'status_text': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Descriptive text for the status",
            nullable=True
        ),
        'address': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Address information",
            nullable=True
        ),
        'links': openapi.Schema(
            type=openapi.TYPE_OBJECT,
            description="Related links"
        ),
        'tags': openapi.Schema(
            type=openapi.TYPE_ARRAY,
            items=tag_schema,
            description="List of tags associated with this hadis"
        ),
        'share_link': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Link for sharing the hadis",
            nullable=True
        ),
        'created_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Creation timestamp"
        )
    },
    required=['status', 'status_color', 'tags', 'created_at']
)

# Hadis detail schema
hadis_detail_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the hadis"
        ),
        'number': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique number identifier for the hadis"
        ),
        'title': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Title of the hadis"
        ),
        'text': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Original text of the hadis"
        ),
        'translation': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Translation of the hadis text"
        ),
        'status': openapi.Schema(
            type=openapi.TYPE_BOOLEAN,
            description="Visibility status of the hadis"
        ),
        'created_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Creation timestamp"
        ),
        'updated_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Last update timestamp"
        ),
        'overview': hadis_overview_schema,
        'first_reference': hadis_reference_schema
    },
    required=['id', 'number', 'title', 'text', 'translation', 'status', 'created_at', 'updated_at', 'overview']
)

hadis_detail_response = openapi.Response(
    description="Detailed information about a specific hadis",
    schema=hadis_detail_schema
)

# Transmitter schema
transmitter_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the transmitter"
        ),
        'full_name': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Full name of the transmitter"
        ),
        'birth_year_hijri': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Birth year in Hijri calendar"
        ),
        'death_year_hijri': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Death year in Hijri calendar"
        ),
        'description': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Description of the transmitter",
            nullable=True
        ),
        'status': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Status of the transmitter"
        ),
        'status_color': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Display color for the status"
        ),
        'thumbnail': openapi.Schema(
            type=openapi.TYPE_OBJECT,
            description="Thumbnail image information",
            nullable=True
        )
    },
    required=['id', 'full_name', 'birth_year_hijri', 'death_year_hijri', 'status', 'status_color']
)

# Hadis transmitter schema
hadis_transmitter_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the hadis transmitter relation"
        ),
        'transmitter': transmitter_schema,
        'description': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Description of the transmitter's role in this hadis",
            nullable=True
        ),
        'order': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Order in the chain of transmission"
        ),
        'created_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Creation timestamp"
        )
    },
    required=['id', 'transmitter', 'order', 'created_at']
)

# Update hadis detail schema to include transmitters
hadis_detail_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the hadis"
        ),
        'number': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique number identifier for the hadis"
        ),
        'title': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Title of the hadis"
        ),
        'text': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Original text of the hadis"
        ),
        'translation': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Translation of the hadis text"
        ),
        'status': openapi.Schema(
            type=openapi.TYPE_BOOLEAN,
            description="Visibility status of the hadis"
        ),
        'created_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Creation timestamp"
        ),
        'updated_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Last update timestamp"
        ),
        'overview': hadis_overview_schema,
        'first_reference': hadis_reference_schema,
        'transmitters': openapi.Schema(
            type=openapi.TYPE_ARRAY,
            items=hadis_transmitter_schema,
            description="List of transmitters for this hadis"
        )
    },
    required=['id', 'number', 'title', 'text', 'translation', 'status', 'created_at', 'updated_at', 'overview']
)

hadis_detail_response = openapi.Response(
    description="Detailed information about a specific hadis",
    schema=hadis_detail_schema
)

# Swagger decorators for views
category_list_swagger = swagger_auto_schema(
    operation_id="list_hadis_categories",
    operation_description="""
    Retrieve a hierarchical tree structure of hadis categories.

    This endpoint returns all hadis categories in a tree structure, with parent categories
    containing their child categories. Each category includes its ID, name, source type,
    category type, and the count of hadis items it contains.

    The response can be filtered by source type (shia or sunni) using the query parameter.
    If no source type is specified, all categories are returned.
    """,
    operation_summary="List Hadis Categories",
    tags=["Hadis"],
    manual_parameters=[source_type_param],
    responses={
        200: categories_response,
        401: "Authentication credentials were not provided or are invalid.",
        500: "Internal server error occurred."
    }
)

category_hadis_list_swagger = swagger_auto_schema(
    operation_id="list_hadis_in_category",
    operation_description="""
    Retrieve a list of hadis items belonging to a specific category.

    This endpoint returns all hadis items that belong to the specified category.
    Each hadis item includes its number, title, original text, translation, and associated tags.

    The category is specified by its ID in the URL path.
    """,
    operation_summary="List Hadis Items in Category",
    tags=["Hadis"],
    responses={
        200: hadis_list_response,
        401: "Authentication credentials were not provided or are invalid.",
        404: "The specified category does not exist.",
        500: "Internal server error occurred."
    }
)

hadis_detail_swagger = swagger_auto_schema(
    operation_id="get_hadis_detail",
    operation_description="""
    Retrieve detailed information about a specific hadis.

    This endpoint returns comprehensive information about a hadis, including:
    - Basic hadis details (number, title, text, translation)
    - HadisOverview information (status, tags, etc.)
    - The first HadisReference with its ReferenceImages
    - List of Transmitters in order of transmission chain

    The hadis is specified by its ID in the URL path.
    """,
    operation_summary="Get Hadis Detail",
    tags=["Hadis"],
    responses={
        200: hadis_detail_response,
        401: "Authentication credentials were not provided or are invalid.",
        404: "The specified hadis does not exist.",
        500: "Internal server error occurred."
    }
)