You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
309 lines
12 KiB
309 lines
12 KiB
"""
|
|
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
|
|
)
|
|
|
|
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
|
|
)
|
|
|
|
author_param = openapi.Parameter(
|
|
'author',
|
|
openapi.IN_QUERY,
|
|
description="Filter books by author slug",
|
|
type=openapi.TYPE_STRING,
|
|
required=False
|
|
)
|
|
|
|
sort_param = openapi.Parameter(
|
|
'sort',
|
|
openapi.IN_QUERY,
|
|
description="Sort books by field. Options: most_popular, newest, most_view, most_rated, 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
|
|
)
|
|
|
|
|
|
thumbs_schema = openapi.Schema(
|
|
type=openapi.TYPE_OBJECT,
|
|
nullable=True,
|
|
properties={
|
|
'sm': openapi.Schema(type=openapi.TYPE_STRING, nullable=True),
|
|
'md': openapi.Schema(type=openapi.TYPE_STRING, nullable=True),
|
|
'lg': openapi.Schema(type=openapi.TYPE_STRING, nullable=True),
|
|
}
|
|
)
|
|
|
|
author_summary_schema = openapi.Schema(
|
|
type=openapi.TYPE_OBJECT,
|
|
properties={
|
|
'id': openapi.Schema(type=openapi.TYPE_INTEGER),
|
|
'full_name': openapi.Schema(type=openapi.TYPE_STRING),
|
|
'slug': openapi.Schema(type=openapi.TYPE_STRING),
|
|
'thumbnail': thumbs_schema,
|
|
}
|
|
)
|
|
|
|
# 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"),
|
|
'summary_title': openapi.Schema(type=openapi.TYPE_STRING, description="Summary title", nullable=True),
|
|
'slogan': openapi.Schema(type=openapi.TYPE_STRING, description="Short slogan", nullable=True),
|
|
'thumbnail': thumbs_schema,
|
|
'author': openapi.Schema(type=openapi.TYPE_STRING, description="Author full name", nullable=True),
|
|
'author_detail': author_summary_schema,
|
|
'publisher': openapi.Schema(type=openapi.TYPE_STRING, description="Publisher", nullable=True),
|
|
'year_of_publication': openapi.Schema(type=openapi.TYPE_STRING, description="Year of publication", nullable=True),
|
|
'isbn': openapi.Schema(type=openapi.TYPE_STRING, description="ISBN", nullable=True),
|
|
'numnber_of_volume': openapi.Schema(type=openapi.TYPE_STRING, description="Volume number", nullable=True),
|
|
'language': openapi.Schema(type=openapi.TYPE_STRING, description="Language code", 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"),
|
|
'share_link': openapi.Schema(type=openapi.TYPE_STRING, nullable=True),
|
|
},
|
|
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 = openapi.Response(
|
|
description="Detailed information about a specific book",
|
|
schema=book_schema
|
|
)
|
|
|
|
author_schema = openapi.Schema(
|
|
type=openapi.TYPE_OBJECT,
|
|
properties={
|
|
'id': openapi.Schema(type=openapi.TYPE_INTEGER, description="Unique identifier for the author"),
|
|
'full_name': openapi.Schema(type=openapi.TYPE_STRING, description="Full name of the author"),
|
|
'slug': openapi.Schema(type=openapi.TYPE_STRING, description="URL-friendly slug for the author"),
|
|
'thumbnail': thumbs_schema,
|
|
'birth_date': openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_DATE, nullable=True, description="Birth date"),
|
|
'death_date': openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_DATE, nullable=True, description="Death date"),
|
|
'books_count': openapi.Schema(type=openapi.TYPE_INTEGER, description="Number of active books"),
|
|
},
|
|
required=['id', 'full_name', 'slug', 'books_count']
|
|
)
|
|
|
|
authors_response = openapi.Response(
|
|
description="List of authors 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=author_schema),
|
|
}
|
|
)
|
|
)
|
|
|
|
author_detail_response = openapi.Response(
|
|
description="Detailed information about a specific author",
|
|
schema=author_schema
|
|
)
|
|
|
|
|
|
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
|
|
- Thumbnail image URLs
|
|
- Author information
|
|
- Status and pin information
|
|
- View and download counts
|
|
- File type and book file URL
|
|
""",
|
|
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.
|
|
|
|
You can filter books by:
|
|
- Collection ID
|
|
- Category slug(s)
|
|
- Author slug
|
|
- Bookmarked books
|
|
|
|
You can search for books by title, summary, publisher, or isbn.
|
|
""",
|
|
operation_summary="List Books",
|
|
tags=["Dobodbi - Library"],
|
|
manual_parameters=[collection_id_param, category_param, author_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.
|
|
""",
|
|
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.
|
|
""",
|
|
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.
|
|
""",
|
|
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."
|
|
}
|
|
)
|
|
|
|
author_list_swagger = swagger_auto_schema(
|
|
operation_id="list_library_authors",
|
|
operation_description="""
|
|
Retrieve a paginated list of library authors.
|
|
|
|
Each author includes thumbnail, full name, and number of active books.
|
|
""",
|
|
operation_summary="List Authors",
|
|
tags=["Dobodbi - Library"],
|
|
responses={
|
|
200: authors_response,
|
|
401: "Authentication credentials were not provided or are invalid.",
|
|
500: "Internal server error occurred."
|
|
}
|
|
)
|
|
|
|
author_detail_swagger = swagger_auto_schema(
|
|
operation_id="get_author_detail",
|
|
operation_description="""
|
|
Retrieve detailed information about a specific author.
|
|
|
|
This endpoint returns full name, birth date, death date, thumbnail, and books count.
|
|
""",
|
|
operation_summary="Get Author Detail",
|
|
tags=["Dobodbi - Library"],
|
|
responses={
|
|
200: author_detail_response,
|
|
401: "Authentication credentials were not provided or are invalid.",
|
|
404: "The specified author does not exist.",
|
|
500: "Internal server error occurred."
|
|
}
|
|
)
|
|
|
|
author_books_swagger = swagger_auto_schema(
|
|
operation_id="list_author_books",
|
|
operation_description="""
|
|
Retrieve a paginated list of books for a specific author.
|
|
|
|
The author is identified by slug in the URL path.
|
|
""",
|
|
operation_summary="List Author Books",
|
|
tags=["Dobodbi - Library"],
|
|
manual_parameters=[is_bookmark_param, search_param, sort_param],
|
|
responses={
|
|
200: books_response,
|
|
401: "Authentication credentials were not provided or are invalid.",
|
|
404: "The specified author does not exist.",
|
|
500: "Internal server error occurred."
|
|
}
|
|
)
|