Dovodi_Backend/apps/library/doc.py

"""
Swagger documentation for the Library API endpoints.

This module provides Swagger documentation for the Library 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

# Parameter definitions
collection_id_param = openapi.Parameter(
    'collection_id',
    openapi.IN_QUERY,
    description="Filter books by collection ID",
    type=openapi.TYPE_INTEGER,
    required=False
)

middle_param = openapi.Parameter(
    'middle',
    openapi.IN_QUERY,
    description="Filter books by middle section collection (any value will trigger the filter)",
    type=openapi.TYPE_STRING,
    required=False
)

bottom_param = openapi.Parameter(
    'bottom',
    openapi.IN_QUERY,
    description="Filter books by bottom section collection (any value will trigger the filter)",
    type=openapi.TYPE_STRING,
    required=False
)

is_bookmark_param = openapi.Parameter(
    'is_bookmark',
    openapi.IN_QUERY,
    description="Filter books that are bookmarked by the current user (set to 'true' to enable)",
    type=openapi.TYPE_BOOLEAN,
    required=False
)

category_param = openapi.Parameter(
    'category',
    openapi.IN_QUERY,
    description="Filter books by category slug(s). Can be a single slug or comma-separated list of slugs",
    type=openapi.TYPE_STRING,
    required=False
)

sort_param = openapi.Parameter(
    'sort',
    openapi.IN_QUERY,
    description="Sort books by field. Options: created_at, -created_at, view_count, -view_count, download_count, -download_count, title, -title, pin, -pin, -pin,-created_at",
    type=openapi.TYPE_STRING,
    required=False
)

search_param = openapi.Parameter(
    'search',
    openapi.IN_QUERY,
    description="Search books by title, summary, publisher, or isbn",
    type=openapi.TYPE_STRING,
    required=False
)

# Response schemas
book_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'id': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Unique identifier for the book"
        ),
        'title': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Title of the book"
        ),
        'slug': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="URL-friendly slug for the book"
        ),
        'summary': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Brief summary of the book"
        ),
        'description': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Detailed description of the book"
        ),
        'thumbnail_url': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="URL to the book's thumbnail image",
            nullable=True
        ),
        'author': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Author of the book"
        ),
        'language': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Language ID of the book",
            nullable=True
        ),
        'main_themes': openapi.Schema(
            type=openapi.TYPE_ARRAY,
            items=openapi.Schema(type=openapi.TYPE_STRING),
            description="List of main themes"
        ),
        'notable_works': openapi.Schema(
            type=openapi.TYPE_ARRAY,
            items=openapi.Schema(type=openapi.TYPE_STRING),
            description="List of notable works"
        ),
        'status': openapi.Schema(
            type=openapi.TYPE_BOOLEAN,
            description="Whether the book is active/visible"
        ),
        'pin': openapi.Schema(
            type=openapi.TYPE_BOOLEAN,
            description="Whether the book is pinned to the top"
        ),
        'view_count': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Number of views for the book"
        ),
        'download_count': openapi.Schema(
            type=openapi.TYPE_INTEGER,
            description="Number of downloads for the book"
        ),
        'file_type': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="Type of the book file (PDF, EPUB, etc.)"
        ),
        'book_file': openapi.Schema(
            type=openapi.TYPE_STRING,
            description="URL to the book file",
            nullable=True
        ),
        'created_at': openapi.Schema(
            type=openapi.TYPE_STRING,
            format=openapi.FORMAT_DATETIME,
            description="Creation timestamp"
        )
    },
    required=['id', 'title', 'slug', 'status', 'created_at']
)

books_response = openapi.Response(
    description="List of books with pagination",
    schema=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'count': openapi.Schema(type=openapi.TYPE_INTEGER),
            'next': openapi.Schema(type=openapi.TYPE_STRING, nullable=True),
            'previous': openapi.Schema(type=openapi.TYPE_STRING, nullable=True),
            'results': openapi.Schema(
                type=openapi.TYPE_ARRAY,
                items=book_schema
            )
        }
    )
)

# Book detail response
book_detail_response = openapi.Response(
    description="Detailed information about a specific book",
    schema=book_schema
)

# Swagger decorators for views
book_detail_swagger = swagger_auto_schema(
    operation_id="get_book_detail",
    operation_description="""
    Retrieve detailed information about a specific book.

    This endpoint returns comprehensive information about a book, including:
    - Basic book details (title, slug, summary, description)
    - Thumbnail image URL
    - Author information
    - Status and pin information
    - View and download counts
    - File type and book file URL
    - Creation and update timestamps
    - Categories and collections the book belongs to
    - Number of pages

    The book is specified by its slug in the URL path.
    """,
    operation_summary="Get Book Detail",
    tags=["Dobodbi - Library"],
    responses={
        200: book_detail_response,
        401: "Authentication credentials were not provided or are invalid.",
        404: "The specified book does not exist.",
        500: "Internal server error occurred."
    }
)

book_list_swagger = swagger_auto_schema(
    operation_id="list_books",
    operation_description="""
    Retrieve a list of books with filtering and search capabilities.

    This endpoint returns a paginated list of books. Each book includes its title, slug,
    summary, description, thumbnail, author, status, pin, view count, download count,
    file type, book file URL, and creation timestamp.

    You can filter books by:
    - Collection ID using the query parameter 'collection_id'
    - Category slug(s) using the query parameter 'category' (single slug or comma-separated list)
    - Bookmarked books using the query parameter 'is_bookmark=true'

    You can also search for books by title, summary, publisher, or isbn using the query parameter 'search'.

    You can sort books by:
    - created_at, -created_at
    - view_count, -view_count
    - download_count, -download_count
    - title, -title
    - pin, -pin, -pin,-created_at
    
    Note: To get downloaded books, use the separate endpoint /books/downloaded/
    """,
    operation_summary="List Books",
    tags=["Dobodbi - Library"],
    manual_parameters=[collection_id_param, category_param, is_bookmark_param, search_param, sort_param],
    responses={
        200: books_response,
        401: "Authentication credentials were not provided or are invalid.",
        500: "Internal server error occurred."
    }
)

category_list_swagger = swagger_auto_schema(
    operation_id="list_categories",
    operation_description="""
    Retrieve a list of book categories.
    
    This endpoint returns a paginated list of book categories. Each category includes its 
    title, slug, status, books count, and timestamps.
    """,
    operation_summary="List Book Categories",
    tags=["Dobodbi - Library"],
    responses={
        200: "List of book categories",
        401: "Authentication credentials were not provided or are invalid.",
        500: "Internal server error occurred."
    }
)

pinned_collection_list_swagger = swagger_auto_schema(
    operation_id="list_pinned_collections",
    operation_description="""
    Retrieve a list of pinned book collections with their top book covers.
    
    This endpoint returns a list of pinned book collections. Each collection includes its 
    title and the covers of its top books by view count.
    """,
    operation_summary="List Pinned Book Collections",
    tags=["Dobodbi - Library"],
    responses={
        200: "List of pinned book collections with covers",
        401: "Authentication credentials were not provided or are invalid.",
        500: "Internal server error occurred."
    }
)

middle_collection_list_swagger = swagger_auto_schema(
    operation_id="list_middle_collections",
    operation_description="""
    Retrieve a list of middle section book collections with their books.
    
    This endpoint returns a list of middle section book collections. Each collection includes its 
    title, slug, summary, status, order, and a list of books in the collection.
    
    Each book in the collection includes its id, title, slug, summary, thumbnail, author, 
    view count, download count, and file type.
    """,
    operation_summary="List Middle Section Book Collections",
    tags=["Dobodbi - Library"],
    responses={
        200: "List of middle section book collections with their books",
        401: "Authentication credentials were not provided or are invalid.",
        500: "Internal server error occurred."
    }
)