from drf_yasg.utils import swagger_auto_schema from drf_yasg import openapi from rest_framework import status # Swagger documentation for HadisSectListView hadis_sect_list_swagger = swagger_auto_schema( operation_description="Get list of all active Hadis sects grouped by sect type (Shia/Sunni)", operation_summary="List Hadis Sects", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="List of hadis sects grouped by type with count", examples={ "application/json": { "count": 4, "results": { "shia": [ { "id": 1, "title": "Twelver Shia", "seo_field": None }, { "id": 2, "title": "Ismaili Shia", "seo_field": None } ], "sunni": [ { "id": 3, "title": "Hanafi", "seo_field": None }, { "id": 4, "title": "Maliki", "seo_field": None } ] } } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for HadisCategoryTreeView hadis_category_tree_swagger = swagger_auto_schema( operation_description=( "Get complete hierarchical tree of Hadis categories grouped by sect type (shia/sunni). " "Categories are not grouped by source_type in the response (mobile filters source_type client-side). " "This sync endpoint returns only category metadata (no hadis payload) for fast offline building of navigation trees." ), operation_summary="Get Complete Hadis Category Tree", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="Complete hierarchical tree grouped by sect with only category metadata (no hadis payloads)", examples={ "application/json": { "count": 6, "results": { "shia": { "sects": { "1": { "id": 1, "sect_type": "shia", "title": "Shi'a Collections", "description": "Shia roots", "order": 1 } }, "categories": [ { "id": 10, "name": "Tafsir", "description": "Quran commentary", "source_type": "quran", "hadis_count": 2, "has_hadis": False, "order": 1, "thumbnail": None, "xmind_file": None, "has_xmind_file": False, "children_count": 3, "children": [ { "id": 11, "name": "Surah Al-Fatiha", "description": "Opening chapter", "source_type": "quran", "hadis_count": 2, "has_hadis": True, "order": 1, "thumbnail": None, "xmind_file": None, "has_xmind_file": False, "father_category": { "id": 10, "name": "Tafsir", "sect_id": 1, "sect_type": "shia", "source_type": "quran" }, "children_count": 3, "children": [] } ] } ] }, "sunni": { "sects": { "2": { "id": 2, "sect_type": "sunni", "title": "Sunni Collections", "description": "Sunni roots", "order": 2 } }, "categories": [ { "id": 20, "name": "Book of Faith", "description": "Iman topics", "source_type": "hadith", "hadis_count": 1, "has_hadis": True, "order": 1, "thumbnail": None, "xmind_file": None, "has_xmind_file": False, "children_count": 3, "children": [] } ] } } } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for HadisSyncView hadis_sync_swagger = swagger_auto_schema( operation_description="Get all Hadis data for offline sync. Returns a dictionary keyed by Hadis ID.", operation_summary="Sync Hadis Data", operation_id="syncHadisData", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'last_updated', openapi.IN_QUERY, description="Timestamp (ISO 8601) to fetch only modified records", type=openapi.TYPE_STRING, required=False ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Successful Sync Response", examples={ "application/json": { "count": 1, "results":[ { "id": 1001, "number": 45, "category_id": 205, "title": "The Reward of Intentions", "title_narrator": "Imam Sadiq (as)", "text": "إنما الأعمال بالنیات...", "translations": { "en": "Actions are but by intentions..." }, "detail": {"address": 'null', "hadis_status": { "id": 130, "title": "Прерванный", "color": "orange" }, "status_text": 'null', "share_link": "https://imamjavad.nwhco.ir/hadis/None", "links": [ { "link": "https://example.com/source1", "title": "Source 1" }, { "link": "https://example.com/source2", "title": "Source 2" } ], "tags": [ { "id": 520, "title": "Постановления" }, { "id": 514, "title": "Терпение" }, ], "references": [ { "id": 2193, "title": 'null', "authors": [], "description": 'null' } ], "reference_images": [ { "id": 1768, "thumbnail": "http://127.0.0.1:8000/media/hadis/reference_images/ref_2193.png", "priority": 0 } ] }, "narrators": { "description": 'null', "transmitters": [ { "id": 53, "name": "Мухаммад ибн аль-Хасан ат-Туси", "reliability": "unknown", "layer_level": 'null', "layer_name": 'null', "is_gap": 'false', "birth_year_hijri": 385, "death_year_hijri": 460, "order": 1 }, { "id": 60, "name": "Мухаммад ибн Муслим", "reliability": "unknown", "layer_level": 'null', "layer_name": 'null', "is_gap": 'false', "birth_year_hijri": 70, "death_year_hijri": 150, "order": 2 }, ] }, "explanations": "Example explanation...", "corrections": [ { "id":"id", 'title':'title', 'description':'description', 'translation':'translation', 'share_link':'share_link' }, ] } ] } } ) } ) # Swagger documentation for HadisListView hadis_list_swagger = swagger_auto_schema( operation_description=""" Retrieve a paginated list of Hadis (traditions) for a specific category. **Key Features:** - Returns hadis entries filtered by category ID - Supports pagination for large datasets - Translations are automatically provided based on the Accept-Language header - Each hadis includes its category information, title, narrator, Arabic text, and translation **Usage:** - Use this endpoint to browse hadis within a specific category - The response includes pagination links (next/previous) for navigation - Set the Accept-Language header to get translations in your preferred language (en, fa, ar, ur) - Only active (status=True) hadis are returned **Response Structure:** - `count`: Total number of hadis in the category - `next`: URL for the next page (null if on last page) - `previous`: URL for the previous page (null if on first page) - `results`: Array of hadis objects with full details """, operation_summary="List Hadis by Category", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'category_id', openapi.IN_PATH, description="Unique identifier of the Hadis category. Must be a valid category ID that exists in the system.", type=openapi.TYPE_INTEGER, required=True, example=1 ), openapi.Parameter( 'page', openapi.IN_QUERY, description="Page number for pagination. Starts from 1. If not provided, returns the first page.", type=openapi.TYPE_INTEGER, required=False, example=1 ), openapi.Parameter( 'Accept-Language', openapi.IN_HEADER, description="Language code for translations. Supported codes: 'en' (English), 'fa' (Persian), 'ar' (Arabic), 'ur' (Urdu). Defaults to 'en' if not specified.", type=openapi.TYPE_STRING, required=False, default='en', enum=['en', 'fa', 'ar', 'ur'] ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Successfully retrieved paginated list of hadis for the specified category", examples={ "application/json": { "count": 150, "next": "http://example.com/api/hadis/category/1/?page=2", "previous": None, "results": [ { "id": 1, "number": 1, "title": "The Opening", "title_narrator": "From Abu Hurairah", "text": "إنما الأعمال بالنيات وإنما لكل امرئ ما نوى", "translation": "Actions are but by intention, and every man shall have only what he intended", "category": { "id": 1, "title": "Book of Faith", "slug": "book-of-faith", "source_type": "hadith", "sect_type": "sunni" }, "share_link": "http://example.com/hadis/1" }, { "id": 2, "number": 2, "title": "The Second Hadith", "title_narrator": "From Umar ibn al-Khattab", "text": "بينما نحن عند رسول الله صلى الله عليه وسلم ذات يوم", "translation": "While we were sitting with the Messenger of Allah (peace be upon him) one day", "category": { "id": 1, "title": "Book of Faith", "slug": "book-of-faith", "source_type": "hadith", "sect_type": "sunni" }, "share_link": "http://example.com/hadis/2" } ] } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="The specified category ID does not exist or the category has no active hadis", examples={ "application/json": { "detail": "Not found." } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error occurred while processing the request" ) } ) hadis_basic_swagger = swagger_auto_schema( operation_description="Get basic information about a specific hadis including core text and translation", operation_summary="Get Hadis Basic Info", operation_id="getHadisBasic", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'hadis_id', openapi.IN_PATH, description="ID of the hadis", type=openapi.TYPE_INTEGER, required=True ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Basic hadis information", examples={ "application/json": { "id": 1, "title": "The Opening", "title_narrator": "From Abu Hurairah", "text": "Actions are but by intention...", "translation": "Actions are but by intention...", "share_link": "http://example.com/hadis/1", 'explanation': "This hadith emphasizes the importance of intention in all actions...", "category": { "id": 330, "title": "Толкование суры Аль-Фатиха", "slug": "cat-slug", "source_type": "quran", "sect_type": "shia" } } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="Hadis not found" ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) hadis_detail_swagger = swagger_auto_schema( operation_summary="Get Hadis Detail Metadata", operation_description="Retrieve metadata for a specific hadis including Status, Tags, External Links, and Book References. (Note: Text and Narrators are in separate endpoints).", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'hadis_id', openapi.IN_PATH, description="ID of the hadis", type=openapi.TYPE_INTEGER, required=True ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Hadis metadata details", examples={ "application/json": { "id": 1800, "number": 1, "hadis_status_text": "Agreed upon by all scholars", "hadis_status": { "id": 130, "title": "Weak / Discontinued", "color": "orange" }, "links": [ { "link": "https://example.com/source1", "title": "Online Reference 1" }, { "link": "https://example.com/source2", "title": "PDF Source" } ], "share_link": "https://imamjavad.nwhco.ir/hadis/1800", "tags": [ { "id": 510, "title": "Hajj (Pilgrimage)" }, { "id": 520, "title": "Legal Rulings" } ], "references": [ { "id": 2193, "book_title": "Sahih al-Bukhari", "book_authors": "Imam Bukhari", "book_description": "Chapter on Patience, Vol 2" } ], "reference_images": [ { "id": 1768, "thumbnail": "http://api.site.com/media/hadis/reference_images/scan_01.png", "priority": 0 } ], "address": "Page 54, Volume 2, Line 10" } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="Hadis not found" ) } ) hadis_transmitters_swagger = swagger_auto_schema( operation_description="Get the chain of transmitters for a specific Hadis. Returns the Hadis ID, the count of unique narrator generations (layers), and the ordered list of transmitters.", operation_summary="Get Hadis Chain (Isnad)", operation_id="getHadisChain", tags=['Hadis'], manual_parameters=[ # Path Parameter: ID openapi.Parameter( 'hadis_id', openapi.IN_PATH, description="The ID of the Hadis to fetch", type=openapi.TYPE_INTEGER, required=True ), # Query Parameter: Layer Filter (Optional) openapi.Parameter( 'layer', openapi.IN_QUERY, description="Filter transmitters by narrator layer slug (e.g., ?layer=sahaba)", type=openapi.TYPE_STRING, required=False ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Successful retrieval of the transmission chain.", examples={ "application/json": { "id": 1800, "layer_count": 3, "results": [ { "id": 5992, "order": 1, "is_gap": False, "narrator_layer_description": "Companions of the Prophet (Sahaba)", "layer": "sahaba", "transmitter": { "id": 53, "full_name": "Abu Hurairah", "birth_year_hijri": 18, "death_year_hijri": 59, "known_as": "Father of the Kitten", "nickname": None, "reliability": "very_reliable", } }, { "id": 5993, "order": 2, "is_gap": False, "narrator_layer_description": "Successors (Tabi'un)", "layer": "tabiun", "transmitter": { "id": 60, "full_name": "Sa'id ibn al-Musayyib", "birth_year_hijri": 15, "death_year_hijri": 94, "known_as": "Sheikh of the Tabi'un", "nickname": None, "reliability": "reliable", "madhhab": "sunni", "generation": 2 } }, { "id": 5995, "order": 3, "is_gap": True, "narrator_layer_description": None, "layer": None, "transmitter": { "id": 59, "full_name": "Unknown Person", "birth_year_hijri": None, "death_year_hijri": None, "known_as": None, "nickname": None, "reliability": "unknown", "madhhab": "unknown", "generation": None } } ] } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="Hadis not found" ) } ) hadis_corrections_swagger = swagger_auto_schema( operation_description=""" Retrieve all corrections, improvements, and scholarly notes for a specific hadis. **Key Features:** - Returns all corrections associated with a hadis - Includes translation corrections in multiple languages - Provides scholarly improvements and clarifications - Useful for understanding updates and refinements to hadis content **Usage:** - Use this endpoint to get corrections and improvements for a hadis - Corrections may include updated translations, authenticity clarifications, or scholarly notes - The `translation` field contains multilingual corrections (typically JSON format) - Each correction has a title and description explaining the nature of the correction **Response Structure:** - `hadis_id`: The ID of the hadis these corrections belong to - `corrections_count`: Total number of corrections available - `corrections`: Array of correction objects with details **Note:** - If no corrections exist, the corrections array will be empty - Corrections are ordered by creation date (newest first) - Translation corrections may be in JSON format with language codes as keys """, operation_summary="Get Hadis Corrections", operation_id="getHadisCorrections", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'hadis_id', openapi.IN_PATH, description="Unique identifier of the hadis. Must be a valid hadis ID that exists in the system. Only active hadis (status=True) are accessible.", type=openapi.TYPE_INTEGER, required=True, example=1 ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Successfully retrieved corrections for the specified hadis", examples={ "application/json": { "hadis_id": 1800, "corrections_count": 2, "corrections": [ { "id": 1, "title": "Translation Correction", "description": "Updated translation for better accuracy and clarity. The previous translation was slightly ambiguous in the context of intention and action.", "translation": { "en": "Actions are judged by intentions, and every person will have what they intended", "ar": "إنما الأعمال بالنيات وإنما لكل امرئ ما نوى", "fa": "اعمال به نیت ها قضاوت می شود و هر کس آنچه را که قصد کرده است خواهد داشت", "ur": "اعمال نیتوں کے مطابق ہیں اور ہر شخص کو وہی ملے گا جس کا اس نے ارادہ کیا" } }, { "id": 2, "title": "Authenticity Clarification", "description": "Additional scholarly notes on the authenticity and grading of this hadith. This hadith is considered authentic (sahih) by consensus of scholars.", "translation": { "en": "This hadith is authentic (sahih) according to the consensus of scholars including Imam Bukhari and Imam Muslim", "ar": "هذا الحديث صحيح حسب إجماع العلماء بما في ذلك الإمام البخاري والإمام مسلم", "fa": "این حدیث طبق اجماع علماء از جمله امام بخاری و امام مسلم صحیح است", "ur": "یہ حدیث علماء کے اجماع کے مطابق صحیح ہے جن میں امام بخاری اور امام مسلم شامل ہیں" } } ] } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="The specified hadis ID does not exist or the hadis is not active", examples={ "application/json": { "detail": "Not found." } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error occurred while processing the request" ) } ) # Swagger documentation for HadisCollectionListView hadis_collections_swagger = swagger_auto_schema( operation_description="Get list of all active hadis collections for browsing and categorization", operation_summary="List Hadis Collections", operation_id="getHadisCollections", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="List of hadis collections", examples={ "application/json": [ { "id": 1, "title": "Collection Title", "description": "Collection description", "order": 1, "status": True } ] } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for HadisInfoView hadis_info_swagger = swagger_auto_schema( operation_description="Get statistical information about hadis database including counts of categories, references, bookmarks, and narrators", operation_summary="Get Hadis Statistics", operation_id="getHadisInfo", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="Hadis database statistics", examples={ "application/json": { "category_count": 25, "reference_count": 150, "bookmark_count": 75, "narrator_count": 200 } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for TransmitterView transmitter_list_swagger = swagger_auto_schema( operation_description="Get a paginated list of transmitters (narrators) with optional filtering by reliability, madhhab, and generation.", operation_summary="List Transmitters", operation_id="listTransmitters", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'status', openapi.IN_QUERY, description='Filter by reliability status (e.g. very_reliable, weak)', type=openapi.TYPE_STRING, required=False ), openapi.Parameter( 'madhhab', openapi.IN_QUERY, description='Filter by madhhab (e.g. shia, sunni)', type=openapi.TYPE_STRING, required=False ), openapi.Parameter( 'generation', openapi.IN_QUERY, description='Filter by generation integer', type=openapi.TYPE_INTEGER, required=False ), ], responses={ status.HTTP_200_OK: openapi.Response( description="Paginated list of transmitters", examples={ "application/json": { "count": 10, "next": "http://api.example.com/transmitters/?page=2", "previous": None, "results": [ { "id": 56, "full_name": "Абу Дауд ас-Сиджистани", "birth_year_hijri": 202, "death_year_hijri": 275, "known_as": "Imam Abu Daud", "nickname": "Al-Sijistani", "reliability": "very_reliable", "madhhab": "sunni", "generation": 3 }, { "id": 51, "full_name": "Мухаммад ибн Якуб Кулейни", "birth_year_hijri": 250, "death_year_hijri": 329, "known_as": "Thiqat al-Islam", "nickname": None, "reliability": "very_reliable", "madhhab": "shia", "generation": 4 } ] } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for TransmitterDetailView transmitter_detail_swagger = swagger_auto_schema( operation_description="Get detailed information about a specific transmitter including their scholarly opinions and hadith transmissions", operation_summary="Get Transmitter Details", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'transmitters_id', openapi.IN_PATH, description="ID of the transmitter", type=openapi.TYPE_INTEGER, required=True ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Detailed transmitter information with nested opinions and transmissions", examples={ "application/json": { "id": 1, "full_name": "Abu Daud Sulaiman ibn al-Ash'ath al-Azdi al-Sijistani", "kunya": "Abu Daud", "known_as": "Imam Abu Daud", "nickname": "Al-Sijistani", "origin": "Sijistan (modern Sistan)", "lived_in": "Basra, Baghdad", "died_in": "Basra", "birth_year_hijri": 202, "death_year_hijri": 275, "age_at_death": 73, "reliability": "very_reliable", "madhhab": "sunni", "in_sahih_bukhari": False, "in_sahih_muslim": True, "description": "Imam Abu Daud, compiler of Sunan Abu Daud", "generation": 3 } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="Transmitter not found" ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) from drf_yasg.utils import swagger_auto_schema from drf_yasg import openapi from rest_framework import status transmitter_sync_swagger = swagger_auto_schema( operation_description="Get complete transmitter (narrator) data for offline synchronization. Returns a flat list of narrators with biographical info.", operation_summary="Sync Transmitter Data", operation_id="syncTransmitterData", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="Complete transmitter data list", examples={ "application/json": { "count": 10, "results": [ { "id": 51, "full_name": "Мухаммад ибн Якуб Кулейни", "biographical": { "full_name": "Мухаммад ибн Якуб Кулейни", "kunya": None, "known_as": None, "nickname": None, "origin": None, "lived_in": None, "died_in": None, "birth_year_hijri": 250, "death_year_hijri": 329, "age_at_death": None, "generation": None, "reliability": "unknown", "madhhab": "unknown", "in_sahih_muslim": False, "in_sahih_bukhari": False, "description": "Шейх Кулейни, автор книги Аль-Кафи и один из великих мухаддисов шиитов", "thumbnail": None }, "scholars_opinions": [ { "id": 2, "scholar_name": "test sc2h", "opinion_text": "some2 opinions", "status": "confirmed", "created_at": "2025-12-16T11:38:19.646613", "updated_at": "2025-12-16T11:38:19.646613" }, { "id": 1, "scholar_name": "test sch", "opinion_text": "some opinions", "status": "confirmed", "created_at": "2025-12-16T11:38:02.679871", "updated_at": "2025-12-16T11:38:02.679871" } ], "original_texts": [ { "id": 1, "title": "text title", "text": "", "translation": { "en": "translate" }, "share_link": "http/exmaokns.com" }, { "id": 2, "title": "text2 title", "text": "", "translation": { "en": "translate" }, "share_link": "http/exmaokns.com" } ] }, { "id": 56, "full_name": "Абу Дауд ас-Сиджистани", "biographical": { "full_name": "Абу Дауд ас-Сиджистани", "kunya": "Abu Daud", "known_as": "Imam Abu Daud", "nickname": "Al-Sijistani", "origin": "Sijistan", "lived_in": "Basra", "died_in": "Basra", "birth_year_hijri": 202, "death_year_hijri": 275, "age_at_death": 73, "generation": 3, "reliability": "very_reliable", "madhhab": "shafii", "in_sahih_muslim": False, "in_sahih_bukhari": False, "description": "Имам Абу Дауд, автор Сунан Абу Дауд", "thumbnail": "http://example.com/media/abu_daud.jpg" }, "scholars_opinions": [], "original_texts": [] } ] } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for TransmitterOpinionView transmitter_opinion_swagger = swagger_auto_schema( operation_description=""" Retrieve all scholarly opinions about a specific transmitter (narrator). **Key Features:** - Returns all opinions from various scholars about the transmitter's reliability and character - Includes opinion status (confirmed, mixed, rejected) - Provides detailed opinion text from each scholar - Useful for understanding the scholarly consensus on a narrator's reliability **Usage:** - Use this endpoint to get scholarly assessments of a transmitter - Opinions help determine the reliability and authenticity of narrations - The `status` field indicates whether the opinion is confirmed, mixed, or rejected - Each opinion includes the scholar's name and their detailed assessment **Response Structure:** - Returns an array of opinion objects - Each opinion includes scholar name, opinion text, status, and timestamps - Opinions are ordered by creation date (newest first) **Opinion Status Values:** - `confirmed`: The opinion is confirmed and widely accepted - `mixed`: There are mixed views about this opinion - `rejected`: The opinion has been rejected or is not widely accepted """, operation_summary="Get Transmitter Opinions", operation_id="getTransmitterOpinions", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'transmitters_id', openapi.IN_PATH, description="Unique identifier of the transmitter (narrator). Must be a valid transmitter ID that exists in the system.", type=openapi.TYPE_INTEGER, required=True, example=56 ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Successfully retrieved all scholarly opinions for the specified transmitter", examples={ "application/json": [ { "id": 1, "transmitter": 56, "scholar_name": "Ibn Hajar al-Asqalani", "opinion_text": "He was a reliable and trustworthy narrator. His narrations are accepted and he is considered among the reliable transmitters of hadith. He had good memory and was known for his accuracy in transmission.", "status": "confirmed", }, { "id": 2, "transmitter": 56, "scholar_name": "Imam al-Dhahabi", "opinion_text": "A reliable narrator with good character. His narrations are generally accepted, though some scholars have noted minor issues in certain chains of transmission.", "status": "mixed", }, { "id": 3, "transmitter": 56, "scholar_name": "Ibn Ma'in", "opinion_text": "Trustworthy and reliable. His narrations are sound and he is considered among the reliable transmitters.", "status": "confirmed", } ] } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="The specified transmitter ID does not exist", examples={ "application/json": { "detail": "Not found." } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error occurred while processing the request" ) } ) # Swagger documentation for TransmitterOriginalTextView transmitter_original_text_swagger = swagger_auto_schema( operation_description=""" Retrieve all original texts associated with a specific transmitter (narrator). **Key Features:** - Returns all original texts (writings, sayings, or works) attributed to the transmitter - Includes original Arabic text and translations in multiple languages - Provides shareable links for each text - Useful for accessing the original works and writings of narrators **Usage:** - Use this endpoint to get original texts written or attributed to a transmitter - Original texts may include their writings, sayings, or scholarly works - The `translation` field contains multilingual translations (typically JSON format) - Each text has a shareable link for easy sharing **Response Structure:** - Returns an array of original text objects - Each text includes title, original text, translations, and share link - Texts are ordered by creation date (newest first) **Translation Format:** - The translation field is typically a JSON array or object - May contain translations in multiple languages - Format may vary based on how translations are stored """, operation_summary="Get Transmitter Original Texts", operation_id="getTransmitterOriginalTexts", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'transmitters_id', openapi.IN_PATH, description="Unique identifier of the transmitter (narrator). Must be a valid transmitter ID that exists in the system.", type=openapi.TYPE_INTEGER, required=True, example=56 ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Successfully retrieved all original texts for the specified transmitter", examples={ "application/json": [ { "id": 1, "title": "On the Importance of Intention", "text": "إنما الأعمال بالنيات وإنما لكل امرئ ما نوى. فمن كانت هجرته إلى الله ورسوله فهجرته إلى الله ورسوله، ومن كانت هجرته لدنيا يصيبها أو امرأة ينكحها فهجرته إلى ما هاجر إليه", "translation": [ { "language_code": "en", "text": "Actions are but by intention, and every person will have what they intended. So whoever emigrated for Allah and His Messenger, then his emigration is for Allah and His Messenger. And whoever emigrated for worldly gain or to marry a woman, then his emigration is for that which he emigrated." }, { "language_code": "fa", "text": "اعمال به نیت ها است و هر کس آنچه را که قصد کرده است خواهد داشت. پس هر کس برای خدا و پیامبرش هجرت کند، هجرت او برای خدا و پیامبرش است. و هر کس برای منافع دنیوی یا ازدواج با زنی هجرت کند، هجرت او برای همان چیزی است که برای آن هجرت کرده است." } ], "share_link": "http://example.com/narrators/56/texts/1" }, { "id": 2, "title": "On Knowledge and Learning", "text": "طلب العلم فريضة على كل مسلم ومسلمة", "translation": [ { "language_code": "en", "text": "Seeking knowledge is obligatory upon every Muslim, male and female" }, { "language_code": "fa", "text": "طلب علم بر هر مسلمان و مسلمانی واجب است" } ], "share_link": "http://example.com/narrators/56/texts/2" } ] } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="The specified transmitter ID does not exist", examples={ "application/json": { "detail": "Not found." } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error occurred while processing the request" ) } ) # Swagger documentation for BookReferencesView book_references_list_swagger = swagger_auto_schema( operation_description=""" Retrieve a paginated list of all book references used in hadith studies. **Key Features:** - Returns a paginated list of book references - Includes metadata such as title, description, rating, and volume info **Response Structure:** - `count`: Total number of books - `results`: Array of book objects - `rate`: The book's rating (returned as a string, e.g., "1.20") - `author`: List of authors associated with the book - `volume`: Volume information (string) """, operation_summary="List Book References", operation_id="listBookReferences", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="Paginated list of book references", examples={ "application/json": { "count": 2, "next": None, "previous": None, "results": [ { "id": 4, "title": "book2", "rate": "1.20", "author": [ { 'id': 5, 'name': 'author.name' }, { 'id': 6, 'name': 'author.name' } ], "description": "book desc", "volume": "9" }, { "id": 2, "title": "book", "rate": "1.20", "author": [ { "id": 1, "name": "Author Name" } ], "description": "book desc", "volume": "9" } ] } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) reference_sync_swagger = swagger_auto_schema( operation_description="Get complete book reference data for offline synchronization. Returns a paginated list of books with detailed metadata.", operation_summary="Sync Book References Data", operation_id="syncReferenceData", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="Complete book references data list", examples={ "application/json": { "count": 2, "next": None, "previous": None, "results": [ { "id": 2, "title": "Sahih Muslim", "rate": "4.80", "author": [ { "id": 55, "name": "Muslim ibn al-Hajjaj" } ], "detail": { "description": "One of the six major collections of Sunni hadith", "volume": "7", "language": "arabic", "isbn": "978-1234567890", "year_of_publication": "261 AH", "number_of_pages": 1200, "volume_info": "7 Volumes", "rating": 4.8 }, "image": [ { "id": 101, "image": "http://api.site.com/media/books/muslim_cover.jpg", "description": "Front Cover", "order": 1 } ], "attribute": [ { "id": 10, "title": "Publisher", "value": "Dar-us-Salam", "book_reference": 2 }, { "id": 11, "title": "Edition", "value": "2nd Edition", "book_reference": 2 } ], "hadises": [ { "id": 1001, "title": "The Book of Faith", "title_narrator": "Abu Huraira", "text": "Faith has seventy-odd branches...", "translation": "Faith has seventy-odd branches...", "share_link": "http://site.com/hadis/1001", } ] }, { "id": 4, "title": "Al-Kafi", "rate": "4.90", "author": [ { "id": 51, "name": "Sheikh Kulayni" } ], "detail": { "description": "The most important Shia hadith collection", "volume": "8", "language": "arabic", "isbn": "978-9876543210", "year_of_publication": "329 AH", "number_of_pages": 3500, "volume_info": "8 Volumes", "rating": 4.9 }, "image": [ { "id": 102, "image": "http://api.site.com/media/books/kafi_cover.jpg", "description": "Volume 1 Cover", "order": 1 } ], "attribute": [ { "id": 12, "title": "Publisher", "value": "Dar al-Kutub al-Islamiyya", "book_reference": 4 } ], "hadises": [] } ] } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for BookAuthorView book_authors_list_swagger = swagger_auto_schema( operation_description="Get list of all book authors who have contributed to hadith literature", operation_summary="List Book Authors", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="List of all book authors", examples={ "application/json": [ { "id": 1, "name": "Muhammad ibn Isma'il al-Bukhari", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" }, { "id": 2, "name": "Muslim ibn al-Hajjaj al-Qushayri", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ] } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error" ) } ) # Swagger documentation for BookDetailView book_detail_swagger = swagger_auto_schema( operation_description=""" Retrieve detailed information about a specific book reference. **Key Features:** - Returns comprehensive details including attributes, authors, images, and referenced hadis. - Matches the `BookDetailSerializer` structure. **Response Structure:** - `attribute`: List of extra book details (e.g., ISBN, Year, Pages). - `author`: List of authors. - `image`: List of book covers or reference images. - `hadis`: List of Hadis that reference this book. """, operation_summary="Get Book Reference Details", operation_id="getBookReferenceDetails", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'bookreference_id', openapi.IN_PATH, description="Unique identifier of the book reference", type=openapi.TYPE_INTEGER, required=True, example=2 ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Detailed book information", examples={ "application/json": { "id": 2, "title": "Sahih Muslim", "rate": "4.80", 'isbn':"13135487d", 'language':'arabic', 'number_page':1000, "publisher": "Dar-us-Salam Publications", "description": "One of the six major collections of Sunni hadith, recognized as authentic.", "volume": "7 Volumes", "slug": "sahih-muslim", "attribute": [ { "id": 10, "title": "ISBN", "value": "978-1234567890" }, { "id": 11, "title": "Pages", "value": "3000" }, { "id": 12, "title": "Language", "value": "Arabic/English" } ], "author": [ { "id": 55, "name": "Muslim ibn al-Hajjaj" } ], "image": [ { "id": 5, "image": "http://api.site.com/media/books/muslim_cover.jpg", "description": "Front Cover", "order": 1 } ], "hadis": [ { "id": 105, "title": "Hadith on Intention", "title_narrator": "Umar ibn Khattab", "text": "Actions are by intentions...", "translation": "Actions are but by intentions...", "share_link": "http://site.com/hadis/105", "explanation": "This hadith signifies the importance of niyyah.", "category": { "id": 50, "title": "Book of Faith" } } ] } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="Book reference not found" ) } ) # Swagger documentation for CategoriesView categories_list_swagger = swagger_auto_schema( operation_description=""" Retrieve a comprehensive list of all Hadis categories in the system. **Key Features:** - Returns all categories regardless of sect type or source type - Includes hierarchical information (children count) - Provides category metadata including sect association, source type, and description - Shows whether categories have direct hadis entries or child categories **Usage:** - Use this endpoint to get an overview of all available categories - The `children_count` field indicates how many subcategories exist - The `has_hadis` field shows if the category directly contains hadis (no children) - The `hadis_count` field shows the total number of hadis in this category **Response Fields:** - `id`: Unique category identifier - `title`: Category name - `sect_id`: Associated sect ID - `sect_type`: Type of Islamic sect (shia/sunni) - `source_type`: Type of source material (quran, hadith, history, fatwa, quote) - `description`: Detailed description of the category - `slug`: URL-friendly identifier - `children_count`: Number of direct child categories - `has_hadis`: Boolean indicating if category has direct hadis entries - `hadis_count`: Total number of hadis in this category """, operation_summary="List All Categories", tags=['Hadis'], responses={ status.HTTP_200_OK: openapi.Response( description="Successfully retrieved list of all hadith categories", examples={ "application/json": [ { "id": 1, "title": "Book of Faith", "sect_id": 1, "sect_type": "sunni", "source_type": "hadith", "description": "Hadiths related to Islamic faith and beliefs, including articles of faith, belief in Allah, angels, books, messengers, and the Last Day", "slug": "book-of-faith", "children_count": 3, "has_hadis": False, "hadis_count": 0 }, { "id": 2, "title": "Book of Prayer", "sect_id": 1, "sect_type": "sunni", "source_type": "hadith", "description": "Hadiths about salah (prayer) and related rulings, including prayer times, conditions, and etiquettes", "slug": "book-of-prayer", "children_count": 0, "has_hadis": True, "hadis_count": 45 }, { "id": 10, "title": "Tafsir of Surah Al-Fatiha", "sect_id": 2, "sect_type": "shia", "source_type": "quran", "description": "Commentary and interpretation of the opening chapter of the Quran", "slug": "tafsir-al-fatiha", "children_count": 0, "has_hadis": True, "hadis_count": 12 } ] } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error occurred while processing the request" ) } ) # Swagger documentation for CategoriesBySectView categories_by_sect_swagger = swagger_auto_schema( operation_description=""" Retrieve a paginated list of Hadis categories filtered by Islamic sect type. **Key Features:** - Filters categories by sect type (shia or sunni) - Returns all categories belonging to the specified sect - Includes hierarchical information (`children_count`) and hadis counts - Useful for building sect-specific category navigation **Usage:** - Use this endpoint to get root categories for a specific Islamic sect - The `sect_type` parameter must be either 'shia' or 'sunni' - Use `next` and `previous` fields for traversing pages **Response Structure:** - Returns a paginated object containing `count` and a `results` array - The `has_hadis` field indicates if the category can be used to fetch hadis directly """, operation_summary="List Categories by Sect", operation_id="listCategoriesBySect", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'sect_type', openapi.IN_PATH, description="Type of Islamic sect. Must be either 'shia' or 'sunni'.", type=openapi.TYPE_STRING, enum=['shia', 'sunni'], required=True, example='sunni' ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Paginated list of categories for the specified sect", examples={ "application/json": { "count": 28, "next": "http://api.site.com/api/hadis/categories/sunni/?limit=16&offset=16", "previous": None, "results": [ { "id": 352, "title": "Толкование Корана", "sect_id": 21, "sect_type": "sunni", "source_type": "quran", "description": None, "slug": "-13", "children_count": 3, "has_hadis": False, "hadis_count": 0 }, { "id": 358, "title": "Толкование суры Аль-Фатиха", "sect_id": 21, "sect_type": "sunni", "source_type": "quran", "description": None, "slug": "-12", "children_count": 0, "has_hadis": False, "hadis_count": 0 }, { "id": 366, "title": "Книга очищения", "sect_id": 21, "sect_type": "sunni", "source_type": "hadith", "description": None, "slug": "-10", "children_count": 3, "has_hadis": False, "hadis_count": 0 } ] } } ), status.HTTP_400_BAD_REQUEST: openapi.Response( description="Invalid parameters", examples={ "application/json": { "detail": "Invalid sect type. Must be 'shia' or 'sunni'." } } ) } ) # Swagger documentation for HadisCategoryTreeBySectView categories_tree_by_sect_swagger = swagger_auto_schema( operation_description=""" Retrieve child categories of a specific parent category within a given Islamic sect type. **Key Features:** - Returns direct children of a parent category identified by slug - Filters by sect type to ensure correct sect association - Provides hierarchical navigation through category tree - Includes information about whether categories have hadis or further children **Usage:** - Use this endpoint to navigate through the category hierarchy - The `slug` parameter identifies the parent category - The `sect_type` ensures categories belong to the correct sect - Use `children_count` to determine if a category has subcategories - Use `has_hadis` to determine if you can fetch hadis directly from this category **Navigation Flow:** 1. Start with root categories (use categories// endpoint) 2. Use the slug from a category to get its children 3. Continue navigating down the tree until you reach a category with `has_hadis: true` 4. Use that category's ID to fetch hadis using the category// endpoint """, operation_summary="Get Category Children by Sect and Slug", operation_id="getCategoryChildrenBySectAndSlug", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'sect_type', openapi.IN_PATH, description="Type of Islamic sect. Must be 'shia' or 'sunni'. This ensures categories belong to the correct sect.", type=openapi.TYPE_STRING, enum=['shia', 'sunni'], required=True, example='shia' ), openapi.Parameter( 'slug', openapi.IN_PATH, description="URL-friendly slug identifier of the parent category. This is used to locate the parent category whose children you want to retrieve. The slug is typically derived from the category title.", type=openapi.TYPE_STRING, required=True, example='book-of-faith' ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Successfully retrieved list of child categories for the specified parent category", examples={ "application/json": { "count": 3, "next": None, "previous": None, "results": [ { "id": 330, "title": "Tafsir of Surah Al-Fatiha", "source_type": "quran", "slug": "tafsir-al-fatiha", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 15 }, { "id": 330, "title": "Tafsir of Surah Al-Fatiha", "source_type": "quran", "slug": "tafsir-al-fatiha", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 15 }, { "id": 330, "title": "Tafsir of Surah Al-Fatiha", "source_type": "quran", "slug": "tafsir-al-fatiha", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 15 }, { "id": 331, "title": "Tafsir of Surah Al-Baqarah", "source_type": "quran", "slug": "tafsir-al-baqarah", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 28 }, { "id": 332, "title": "Tafsir of Surah Al-Imran", "source_type": "quran", "slug": "tafsir-al-imran", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 22 } ] } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="Parent category with the specified slug not found in the given sect type", examples={ "application/json": { "detail": "No categories found for the specified slug and sect type." } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error occurred while processing the request" ) } ) # Swagger documentation for HadisCategoryTreeBySectSourceView categories_tree_by_sect_source_swagger = swagger_auto_schema( operation_description=""" Retrieve child categories of a specific parent category, filtered by sect type and source material type. **Key Features:** - Returns direct children of a parent category identified by slug - Filters by both sect type and source type for precise navigation - Useful for filtering categories by source material (Quran, Hadith, History, Fatwa, Quote) - Provides hierarchical navigation with source-specific filtering **Usage:** - Use this endpoint when you need to filter categories by source material type - The `source_type` parameter allows filtering by: 'quran', 'hadith', 'history', 'fatwa', or 'quote' - This is useful for building source-specific category navigation - Combine with sect type to get categories for a specific sect and source combination **Source Types:** - `quran`: Categories related to Quranic commentary and interpretation - `hadith`: Categories containing prophetic traditions - `history`: Historical accounts and narratives - `fatwa`: Legal opinions and religious rulings - `quote`: Quotations and sayings **Navigation Flow:** 1. Start with root categories filtered by sect and source type 2. Use the slug from a category to get its children (with same source type) 3. Continue until you reach a category with `has_hadis: true` 4. Use that category's ID to fetch hadis """, operation_summary="Get Category Children by Sect, Slug and Source", operation_id="getCategoryChildrenBySectSlugAndSource", tags=['Hadis'], manual_parameters=[ openapi.Parameter( 'sect_type', openapi.IN_PATH, description="Type of Islamic sect. Must be 'shia' or 'sunni'. Ensures categories belong to the correct sect.", type=openapi.TYPE_STRING, enum=['shia', 'sunni'], required=True, example='shia' ), openapi.Parameter( 'slug', openapi.IN_PATH, description="URL-friendly slug identifier of the parent category.", type=openapi.TYPE_STRING, required=True, example='quran-commentary' ), openapi.Parameter( 'source_type', openapi.IN_PATH, description="Type of source material. Filters children to only those matching this source type.", type=openapi.TYPE_STRING, enum=['quran', 'hadith', 'history', 'fatwa', 'quote'], required=True, example='quran' ) ], responses={ status.HTTP_200_OK: openapi.Response( description="Paginated list of child categories filtered by sect type and source type", examples={ "application/json": { "count": 3, "next": None, "previous": None, "results": [ { "id": 330, "title": "Толкование суры Аль-Фатиха", "source_type": "quran", "slug": "", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 10 }, { "id": 331, "title": "Толкование суры Аль-Бакара", "source_type": "quran", "slug": "-16", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 10 }, { "id": 332, "title": "Толкование суры Аль Имран", "source_type": "quran", "slug": "-32", "sect_id": 20, "sect_type": "shia", "children_count": 0, "has_hadis": True, "hadis_count": 10 } ] } } ), status.HTTP_404_NOT_FOUND: openapi.Response( description="Parent category not found or no children exist", examples={ "application/json": { "detail": "No categories found matching the specified criteria." } } ), status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response( description="Internal server error occurred while processing the request" ) } )