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

# 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."
    }
)