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.
2690 lines
112 KiB
2690 lines
112 KiB
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=['Dobodbi - Hadis'],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="List of hadis sects grouped by type with count",
|
|
examples={
|
|
"application/json": {
|
|
"count": 2,
|
|
"next": 'null',
|
|
"previous": 'null',
|
|
"results": [
|
|
{
|
|
"id": 20,
|
|
"sect_type": "shia",
|
|
"title": "Шииты-двунадесятники",
|
|
"order":1,
|
|
"description": [],
|
|
"source_types": [
|
|
"hadith",
|
|
"quote",
|
|
"quran"
|
|
]
|
|
},
|
|
{
|
|
"id": 21,
|
|
"sect_type": "sunni",
|
|
"title": "Сунниты",
|
|
"order":1,
|
|
"description": [],
|
|
"source_types": [
|
|
"fatwa",
|
|
"hadith",
|
|
"history",
|
|
"quran"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
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. Includes sect information and full category tree with hadis counts and children counts."
|
|
),
|
|
operation_summary="Get Complete Hadis Category Tree",
|
|
tags=['Dobodbi - Hadis'],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Complete hierarchical tree grouped by sect with category metadata including hadis counts and children counts",
|
|
examples={
|
|
"application/json": {
|
|
"count": 6,
|
|
"results": {
|
|
"shia": {
|
|
"sects": {
|
|
"1": {
|
|
"id": 1,
|
|
"sect_type": "shia",
|
|
"title": "Shi'a Collections",
|
|
"description": "Shia roots",
|
|
"order": 1,
|
|
"source_types": [
|
|
"hadith",
|
|
"quran",
|
|
"quote"
|
|
]
|
|
|
|
}
|
|
},
|
|
"categories": [
|
|
{
|
|
"id": 10,
|
|
"title": "Tafsir",
|
|
"description": "Quran commentary",
|
|
"slug": "-330",
|
|
"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,
|
|
"title": "Surah Al-Fatiha",
|
|
"description": "Opening chapter",
|
|
"slug": "-330",
|
|
"source_type": "quran",
|
|
"hadis_count": 2,
|
|
"has_hadis": True,
|
|
"order": 1,
|
|
"thumbnail": None,
|
|
"xmind_file": None,
|
|
"has_xmind_file": False,
|
|
"children_count": 3,
|
|
"children": []
|
|
}
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"sunni": {
|
|
"sects": {
|
|
"2": {
|
|
"id": 2,
|
|
"sect_type": "sunni",
|
|
"title": "Sunni Collections",
|
|
"description": "Sunni roots",
|
|
"order": 2,
|
|
"source_types": [
|
|
"hadith",
|
|
"quran",
|
|
"quote"
|
|
]
|
|
}
|
|
},
|
|
"categories": [
|
|
{
|
|
"id": 20,
|
|
"title": "Book of Faith",
|
|
"description": "Iman topics",
|
|
"slug": "-330",
|
|
"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=['Dobodbi - 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,
|
|
"slug": "достоинство-молитвы-и-ее-место-в-религии",
|
|
"category_id": 205,
|
|
"title": "The Reward of Intentions",
|
|
"title_narrator": "Imam Sadiq (as)",
|
|
"text": "إنما الأعمال بالنیات...",
|
|
"translation": "hadis translation",
|
|
"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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'category_slug',
|
|
openapi.IN_PATH,
|
|
description="Unique identifier of the Hadis category. Must be a valid category ID that exists in the system.",
|
|
type=openapi.TYPE_STRING,
|
|
required=True,
|
|
example='-330'
|
|
),
|
|
openapi.Parameter(
|
|
'is_bookmark',
|
|
openapi.IN_QUERY,
|
|
description="Filter only bookmarked hadis for the authenticated user",
|
|
type=openapi.TYPE_BOOLEAN,
|
|
required=False,
|
|
default=False
|
|
),
|
|
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"
|
|
},
|
|
"status": {
|
|
"id": 130,
|
|
"title": "Прерванный",
|
|
"color": "orange"
|
|
},
|
|
"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"
|
|
},
|
|
"status": {
|
|
"id": 130,
|
|
"title": "Прерванный",
|
|
"color": "orange"
|
|
},
|
|
"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"
|
|
)
|
|
}
|
|
)
|
|
|
|
|
|
arguments_filters_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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
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": {
|
|
"statuses": [
|
|
{
|
|
"text": "Достоверный",
|
|
"slug": "-0"
|
|
},
|
|
{
|
|
"text": "Authentic / Accepted",
|
|
"slug": "authentic-accepted-1"
|
|
},
|
|
{
|
|
"text": "Weak / Needs Review",
|
|
"slug": "weak-needs-review-2"
|
|
},
|
|
{
|
|
"text": "Хороший",
|
|
"slug": "-3"
|
|
},
|
|
],
|
|
"categories": [
|
|
{
|
|
"text": "Толкование суры Аль-Фатиха",
|
|
"slug": "-330"
|
|
},
|
|
{
|
|
"text": "Аяты о молитве",
|
|
"slug": "-15"
|
|
},
|
|
{
|
|
"text": "Истории пророков",
|
|
"slug": "-14"
|
|
},
|
|
]
|
|
}
|
|
}
|
|
),
|
|
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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'hadis_slug',
|
|
openapi.IN_PATH,
|
|
description="Slug of the hadis",
|
|
type=openapi.TYPE_STRING,
|
|
required=True
|
|
)
|
|
],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Basic hadis information",
|
|
examples={
|
|
"application/json": {
|
|
"id": 1,
|
|
"slug": "достоинство-молитвы-и-ее-место-в-религии",
|
|
"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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'hadis_slug',
|
|
openapi.IN_PATH,
|
|
description="Slug of the hadis",
|
|
type=openapi.TYPE_STRING,
|
|
required=True
|
|
)
|
|
],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Hadis metadata details",
|
|
examples={
|
|
"application/json": {
|
|
"id": 1800,
|
|
"slug": "достоинство-молитвы-и-ее-место-в-религии",
|
|
"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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
# Path Parameter: ID
|
|
openapi.Parameter(
|
|
'hadis_slug',
|
|
openapi.IN_PATH,
|
|
description="The Slug of the Hadis to fetch",
|
|
type=openapi.TYPE_STRING,
|
|
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": 1830,
|
|
"layer_count": 2,
|
|
"layer_names": [
|
|
"Students of the Imams",
|
|
"Minor Narrators"
|
|
],
|
|
"results": [
|
|
{
|
|
"id": 6609,
|
|
"order": 0,
|
|
"is_gap": False,
|
|
"narrator_layer_description": "Lesser known narrators",
|
|
"layer": "minor-narrators",
|
|
"transmitter": {
|
|
"id": 90,
|
|
"full_name": "Sahl bin Ziyad",
|
|
"birth_year_hijri": 'null',
|
|
"death_year_hijri": 255,
|
|
"known_as": 'null',
|
|
"nickname": 'null',
|
|
"reliability": 10
|
|
},
|
|
"status": {
|
|
"id": 10,
|
|
"title": "Weak",
|
|
"slug": "weak",
|
|
"color": "orange"
|
|
}
|
|
},
|
|
{
|
|
"id": 6610,
|
|
"order": 1,
|
|
"is_gap": False,
|
|
"narrator_layer_description": "Lesser known narrators",
|
|
"layer": "minor-narrators",
|
|
"transmitter": {
|
|
"id": 87,
|
|
"full_name": "Yunus bin Abd al-Rahman",
|
|
"birth_year_hijri": 'null',
|
|
"death_year_hijri": 208,
|
|
"known_as": 'null',
|
|
"nickname": 'null',
|
|
"reliability": 7
|
|
},
|
|
"status": {
|
|
"id": 7,
|
|
"title": "Very Reliable",
|
|
"slug": "very-reliable",
|
|
"color": "green"
|
|
}
|
|
},
|
|
{
|
|
"id": 6611,
|
|
"order": 2,
|
|
"is_gap": False,
|
|
"narrator_layer_description": "Direct students of the Imams",
|
|
"layer": "students-of-the-imams",
|
|
"transmitter": {
|
|
"id": 84,
|
|
"full_name": "Zurarah bin Ayan",
|
|
"birth_year_hijri": 'null',
|
|
"death_year_hijri": 150,
|
|
"known_as": 'null',
|
|
"nickname": 'null',
|
|
"reliability": 7
|
|
},
|
|
"status": {
|
|
"id": 7,
|
|
"title": "Very Reliable",
|
|
"slug": "very-reliable",
|
|
"color": "green"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'hadis_slug',
|
|
openapi.IN_PATH,
|
|
description="Slug of the hadis. Must be a valid hadis slug that exists in the system. Only active hadis (status=True) are accessible.",
|
|
type=openapi.TYPE_STRING,
|
|
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",
|
|
"slug":"достоинство-молитвы-и-ее-место-в-религии",
|
|
"description": "Updated translation for better accuracy and clarity. The previous translation was slightly ambiguous in the context of intention and action.",
|
|
"translation":"Actions are judged by intentions, and every person will have what they intended",
|
|
"share_link": 'null'
|
|
},
|
|
{
|
|
"id": 2,
|
|
"title": "Authenticity Clarification",
|
|
"slug":"достоинство-молитвы-и-ее-место-в-религии",
|
|
"description": "Additional scholarly notes on the authenticity and grading of this hadith. This hadith is considered authentic (sahih) by consensus of scholars.",
|
|
"translation":"Actions are judged by intentions, and every person will have what they intended",
|
|
"share_link": 'null'
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
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"
|
|
)
|
|
}
|
|
)
|
|
|
|
hadis_layers_swagger = swagger_auto_schema(
|
|
operation_description="""
|
|
Get all narrator layers (Tabaqat) associated with a specific hadis.
|
|
|
|
**Key Features:**
|
|
- Returns all unique narrator layers that appear in the transmission chain of a hadis
|
|
- Each layer includes name, slug, and description information
|
|
- Layers are ordered by their numerical order (generation/classification level)
|
|
- Useful for understanding the different generations of narrators in a hadis chain
|
|
|
|
**Usage:**
|
|
- Use this endpoint to get the narrator layers for a specific hadis
|
|
- The layers represent different generations or classifications of narrators (e.g., Sahaba, Tabi'un, etc.)
|
|
- Each layer has a localized name and description
|
|
- The slug can be used for filtering transmitters by layer
|
|
|
|
**Response Structure:**
|
|
- `count`: Total number of layers for this hadis
|
|
- `next/previous`: Pagination links (typically null for this endpoint)
|
|
- `results`: Array of layer objects with name, slug, and description
|
|
|
|
**Note:**
|
|
- Only layers that have narrators in this specific hadis are returned
|
|
- Layers are ordered by their numerical layer number
|
|
- If no layers are found, the results array will be empty
|
|
""",
|
|
operation_summary="Get Hadis Narrator Layers",
|
|
operation_id="getHadisLayers",
|
|
tags=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'hadis_slug',
|
|
openapi.IN_PATH,
|
|
description="Slug of the hadis. Must be a valid hadis slug that exists in the system. Only active hadis (status=True) are accessible.",
|
|
type=openapi.TYPE_STRING,
|
|
required=True,
|
|
example="hadis-ru-261-f7de1cbf"
|
|
)
|
|
],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Successfully retrieved narrator layers for the specified hadis",
|
|
examples={
|
|
"application/json": {
|
|
"count": 2,
|
|
"next": None,
|
|
"previous": None,
|
|
"results": [
|
|
{
|
|
"name": "Students of the Imams",
|
|
"slug": "students-of-the-imams",
|
|
"description": "Direct students of the Imams of Ahl al-Bayt"
|
|
},
|
|
{
|
|
"name": "Minor Narrators",
|
|
"slug": "minor-narrators",
|
|
"description": "Lesser known narrators"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_404_NOT_FOUND: openapi.Response(
|
|
description="The specified hadis slug 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=['Dobodbi - Hadis'],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="List of hadis collections",
|
|
examples={
|
|
"application/json": [
|
|
{
|
|
"count": 2,
|
|
"next": 'null',
|
|
"previous": 'null',
|
|
"results": [
|
|
{
|
|
"id": 9,
|
|
"title": "The Book of Intellect and Ignorance",
|
|
"summary": "A collection of narrations regarding the importance of reason.",
|
|
"slug": "the-book-of-intellect-and-ignorance",
|
|
"thumbnail": 'null'
|
|
},
|
|
{
|
|
"id": 10,
|
|
"title": "The Book of Monotheism",
|
|
"summary": "Hadiths explaining the oneness of God.",
|
|
"slug": "the-book-of-monotheism",
|
|
"thumbnail": 'null'
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
),
|
|
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=['Dobodbi - Hadis'],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Hadis database statistics",
|
|
examples={
|
|
"application/json":{
|
|
"hadis_count": 65,
|
|
"category_count": 67,
|
|
"reference_count": 1,
|
|
"bookmark_count": 0,
|
|
"narrator_count": 8
|
|
}
|
|
}
|
|
),
|
|
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=['Dobodbi - 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": "Абу Дауд ас-Сиджистани",
|
|
"slug": "abdullah-ibn-abbas",
|
|
"birth_year_hijri": 202,
|
|
"death_year_hijri": 275,
|
|
"known_as": "Imam Abu Daud",
|
|
"nickname": "Al-Sijistani",
|
|
"reliability": {
|
|
"id": 7,
|
|
"title": "Very Reliable",
|
|
"color": "green"
|
|
},
|
|
"madhhab": "sunni",
|
|
"generation": 3
|
|
},
|
|
{
|
|
"id": 51,
|
|
"full_name": "Мухаммад ибн Якуб Кулейни",
|
|
"slug": "abdullah-ibn-abbas",
|
|
"birth_year_hijri": 250,
|
|
"death_year_hijri": 329,
|
|
"known_as": "Thiqat al-Islam",
|
|
"nickname": None,
|
|
"reliability": {
|
|
"id": 7,
|
|
"title": "Very Reliable",
|
|
"color": "green"
|
|
},
|
|
"madhhab": "shia",
|
|
"generation": 4
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response(
|
|
description="Internal server error"
|
|
)
|
|
}
|
|
)
|
|
|
|
transmitter_filters_swagger = swagger_auto_schema(
|
|
operation_description="Get the needed data for filter lists such as madhabs,generations,reliabilities.",
|
|
operation_summary="Transmitter's List's filters",
|
|
operation_id="transmiterfilter",
|
|
tags=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'Accept-Language',
|
|
openapi.IN_HEADER,
|
|
description="Language code for localized content. Supported codes: 'en' (English), 'fa' (Persian), 'ar' (Arabic), 'ur' (Urdu), 'ru' (Russian). Defaults to 'en' if not specified.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
default='en',
|
|
enum=['en', 'fa', 'ar', 'ur', 'ru']
|
|
)
|
|
],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="list of transmitters filter data",
|
|
examples={
|
|
"application/json": {
|
|
"generations": [1,2,3,4,5],
|
|
"madhabs": [
|
|
"shia",
|
|
"sunni"
|
|
],
|
|
"reliabilities": [
|
|
{
|
|
"text": "Very Reliable",
|
|
"slug": "very-reliable"
|
|
},
|
|
{
|
|
"text": "Reliable",
|
|
"slug": "reliable"
|
|
},
|
|
{
|
|
"text": "Acceptable",
|
|
"slug": "acceptable"
|
|
},
|
|
{
|
|
"text": "Weak",
|
|
"slug": "weak"
|
|
},
|
|
{
|
|
"text": "Very Weak",
|
|
"slug": "very-weak"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'narrator_slug',
|
|
openapi.IN_PATH,
|
|
description="Slug of narrator",
|
|
type=openapi.TYPE_STRING,
|
|
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": {
|
|
"id": 7,
|
|
"title": "Very Reliable",
|
|
"color": "green"
|
|
},
|
|
"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=['Dobodbi - Hadis'],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Complete transmitter data list",
|
|
examples={
|
|
"application/json": {
|
|
"count": 10,
|
|
"results": [
|
|
{
|
|
"id": 51,
|
|
"full_name": "Мухаммад ибн Якуб Кулейни",
|
|
"slug": "zurarah-bin-ayan",
|
|
"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": {
|
|
"id": 7,
|
|
"title": "Very Reliable",
|
|
"color": "green"
|
|
},
|
|
"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": {
|
|
"id": 1,
|
|
"title": "accepted",
|
|
"slug": "accepted",
|
|
"color": "green"
|
|
},
|
|
"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": {
|
|
"id": 1,
|
|
"title": "accepted",
|
|
"slug": "accepted",
|
|
"color": "green"
|
|
},
|
|
"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":"text translation",
|
|
"share_link": "http/exmaokns.com"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"title": "text2 title",
|
|
"text": "",
|
|
"translation":"text translation",
|
|
"share_link": "http/exmaokns.com"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": 56,
|
|
"full_name": "Абу Дауд ас-Сиджистани",
|
|
"slug": "zurarah-bin-ayan",
|
|
"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": {
|
|
"id": 7,
|
|
"title": "Very Reliable",
|
|
"color": "green"
|
|
},
|
|
"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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'narrator_slug',
|
|
openapi.IN_PATH,
|
|
description="Narrator's slug",
|
|
type=openapi.TYPE_STRING,
|
|
required=True,
|
|
example="abdullah-ibn-abbas"
|
|
)
|
|
],
|
|
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": {
|
|
"id": 1,
|
|
"title": "accepted",
|
|
"slug": "accepted",
|
|
"color": "green"
|
|
}
|
|
},
|
|
{
|
|
"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": {
|
|
"id": 1,
|
|
"title": "accepted",
|
|
"slug": "accepted",
|
|
"color": "green"
|
|
}
|
|
},
|
|
{
|
|
"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": {
|
|
"id": 1,
|
|
"title": "accepted",
|
|
"slug": "accepted",
|
|
"color": "green"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
),
|
|
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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'narrator_slug',
|
|
openapi.IN_PATH,
|
|
description="Narrator's slug",
|
|
type=openapi.TYPE_STRING,
|
|
required=True,
|
|
example="abdullah-ibn-abbas"
|
|
)
|
|
],
|
|
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":"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.",
|
|
"share_link": "http://example.com/narrators/56/texts/1"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"title": "On Knowledge and Learning",
|
|
"text": "طلب العلم فريضة على كل مسلم ومسلمة",
|
|
"translation":"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.",
|
|
"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
|
|
- Supports search functionality for book titles
|
|
- Includes metadata such as title, description, rating, and volume info
|
|
|
|
**Search Functionality:**
|
|
- Search parameter performs case-insensitive search across book titles
|
|
- Supports partial matching for easy discovery
|
|
|
|
**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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'search',
|
|
openapi.IN_QUERY,
|
|
description="Search term to filter book references by title. Case-insensitive partial matching.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
example="sahih"
|
|
)
|
|
],
|
|
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",
|
|
"slug": "al-mizan",
|
|
"rate": "1.20",
|
|
"author": [
|
|
{
|
|
'id': 5,
|
|
'name': 'author.name'
|
|
},
|
|
{
|
|
'id': 6,
|
|
'name': 'author.name'
|
|
}
|
|
],
|
|
"description": "book desc",
|
|
"volume": "9"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"title": "book",
|
|
"slug": "al-mizan",
|
|
"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=['Dobodbi - 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=['Dobodbi - 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"
|
|
)
|
|
}
|
|
)
|
|
|
|
# ============================================================================
|
|
# GET - List all book attributes
|
|
# ============================================================================
|
|
book_attributes_list_swagger = swagger_auto_schema(
|
|
operation_description="Retrieve all custom attributes for books. Optionally filter by book reference ID or attribute title.",
|
|
operation_summary="List Book Attributes",
|
|
tags=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'book_reference',
|
|
openapi.IN_QUERY,
|
|
description='Filter attributes by book reference ID (optional)',
|
|
type=openapi.TYPE_INTEGER,
|
|
required=False,
|
|
),
|
|
openapi.Parameter(
|
|
'title',
|
|
openapi.IN_QUERY,
|
|
description='Filter attributes by title - partial match (optional)',
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
),
|
|
openapi.Parameter(
|
|
'limit',
|
|
openapi.IN_QUERY,
|
|
description='Number of results per page',
|
|
type=openapi.TYPE_INTEGER,
|
|
required=False,
|
|
),
|
|
openapi.Parameter(
|
|
'offset',
|
|
openapi.IN_QUERY,
|
|
description='Starting index for pagination',
|
|
type=openapi.TYPE_INTEGER,
|
|
required=False,
|
|
),
|
|
],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="List of book attributes retrieved successfully",
|
|
examples={
|
|
"application/json": {
|
|
"count": 2,
|
|
"next": None,
|
|
"previous": None,
|
|
"results": [
|
|
{
|
|
"id": 1,
|
|
"title": "Number of Hadith",
|
|
"value": "7,563",
|
|
"book_reference": 1
|
|
},
|
|
{
|
|
"id": 2,
|
|
"title": "Authenticity Grade",
|
|
"value": "Sahih (Authentic)",
|
|
"book_reference": 1
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_400_BAD_REQUEST: openapi.Response(
|
|
description="Invalid query parameters",
|
|
examples={
|
|
"application/json": {
|
|
"error": "Invalid book_reference ID"
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response(
|
|
description="Internal server error"
|
|
)
|
|
}
|
|
)
|
|
|
|
# ============================================================================
|
|
# POST - Create a new book attribute
|
|
# ============================================================================
|
|
book_attributes_create_swagger = swagger_auto_schema(
|
|
operation_description="Create a new custom attribute for a book. Attributes can store additional metadata about hadith books such as number of hadith, authenticity grade, or other relevant information.",
|
|
operation_summary="Create Book Attribute",
|
|
tags=['Dobodbi - Hadis'],
|
|
request_body=openapi.Schema(
|
|
type=openapi.TYPE_OBJECT,
|
|
required=['title', 'value', 'book_reference'],
|
|
properties={
|
|
'title': openapi.Schema(
|
|
type=openapi.TYPE_STRING,
|
|
description='Attribute title/name (e.g., "Number of Hadith")',
|
|
example='Collection Type'
|
|
),
|
|
'value': openapi.Schema(
|
|
type=openapi.TYPE_STRING,
|
|
description='Attribute value (e.g., "7,563")',
|
|
example='Hadith Compilation'
|
|
),
|
|
'book_reference': openapi.Schema(
|
|
type=openapi.TYPE_INTEGER,
|
|
description='ID of the book this attribute belongs to',
|
|
example=2
|
|
),
|
|
}
|
|
),
|
|
responses={
|
|
status.HTTP_201_CREATED: openapi.Response(
|
|
description="Book attribute created successfully",
|
|
examples={
|
|
"application/json": {
|
|
"id": 3,
|
|
"title": "Collection Type",
|
|
"value": "Hadith Compilation",
|
|
"book_reference": 2
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_400_BAD_REQUEST: openapi.Response(
|
|
description="Invalid input data",
|
|
examples={
|
|
"application/json": {
|
|
"title": ["This field is required."],
|
|
"value": ["This field is required."],
|
|
"book_reference": ["Invalid book reference ID."]
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_401_UNAUTHORIZED: openapi.Response(
|
|
description="Authentication required - provide a valid token"
|
|
),
|
|
status.HTTP_403_FORBIDDEN: openapi.Response(
|
|
description="Permission denied - you do not have permission to create attributes"
|
|
),
|
|
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=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'reference_slug',
|
|
openapi.IN_PATH,
|
|
description="Unique slug of the book reference",
|
|
type=openapi.TYPE_STRING,
|
|
required=True,
|
|
example='sunan-ibn-majah'
|
|
)
|
|
],
|
|
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=['Dobodbi - 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=['Dobodbi - 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/<sect_type>/ 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/<category_id>/ endpoint
|
|
""",
|
|
operation_summary="Get Category Children by Sect and Slug",
|
|
operation_id="getCategoryChildrenBySectAndSlug",
|
|
tags=['Dobodbi - 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",
|
|
"description": "Commentary and interpretation of the opening chapter of the Quran",
|
|
"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",
|
|
"description": "Detailed explanation of Surah Al-Baqarah verses and their meanings",
|
|
"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",
|
|
"description": "Interpretation of Surah Al-Imran with scholarly insights",
|
|
"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=['Dobodbi - 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",
|
|
"description": "Commentary and interpretation of the opening chapter of the Quran",
|
|
"children_count": 0,
|
|
"has_hadis": True,
|
|
"hadis_count": 10
|
|
},
|
|
{
|
|
"id": 331,
|
|
"title": "Толкование суры Аль-Бакара",
|
|
"source_type": "quran",
|
|
"slug": "-16",
|
|
"sect_id": 20,
|
|
"sect_type": "shia",
|
|
"description": "Detailed explanation of Surah Al-Baqarah verses and their meanings",
|
|
"children_count": 0,
|
|
"has_hadis": True,
|
|
"hadis_count": 10
|
|
},
|
|
{
|
|
"id": 332,
|
|
"title": "Толкование суры Аль Имран",
|
|
"source_type": "quran",
|
|
"slug": "-32",
|
|
"sect_id": 20,
|
|
"sect_type": "shia",
|
|
"description": "Interpretation of Surah Al-Imran with scholarly insights",
|
|
"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"
|
|
)
|
|
}
|
|
)
|
|
|
|
|
|
# Swagger documentation for HadisMainListView
|
|
hadis_main_list_swagger = swagger_auto_schema(
|
|
operation_description="""
|
|
Retrieve a comprehensive list of all Hadis (traditions) with advanced search and filtering capabilities.
|
|
|
|
**Key Features:**
|
|
- Returns all active hadis entries with their complete information
|
|
- Supports full-text search across titles, narrator titles, Arabic text, and translations
|
|
- Filter by hadis status and category titles
|
|
- Includes complete category and status metadata in the response
|
|
- Supports pagination for large result sets
|
|
- Translations are automatically provided based on the Accept-Language header
|
|
|
|
**Search Functionality:**
|
|
- Search parameter performs case-insensitive search across:
|
|
- Hadis titles (localized)
|
|
- Narrator titles (localized)
|
|
- Arabic text content
|
|
- Translation text (localized)
|
|
|
|
**Filtering Options:**
|
|
- `status`: Filter by hadis status title (e.g., "authentic", "weak")
|
|
- `category`: Filter by category title (e.g., "prayer", "faith")
|
|
|
|
**Pagination:**
|
|
- Use `page` parameter to navigate through pages (starts from 1)
|
|
- Use `page_size` parameter to control items per page
|
|
- Response includes `next` and `previous` URLs for navigation
|
|
|
|
**Response Structure:**
|
|
- `count`: Total number of hadis matching the criteria (not just current page)
|
|
- `next`: URL for the next page (null if on last page)
|
|
- `previous`: URL for the previous page (null if on first page)
|
|
- `categories`: List of all available categories with localized titles
|
|
- `statuses`: List of all available hadis statuses with localized titles
|
|
- `results`: Array of hadis objects for the current page with full details including individual status
|
|
""",
|
|
operation_summary="List All Hadis with Search & Filters",
|
|
tags=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'search',
|
|
openapi.IN_QUERY,
|
|
description="Search term to filter hadis. Searches across titles, narrator titles, Arabic text, and translations. Case-insensitive partial matching.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
example="prayer"
|
|
),
|
|
openapi.Parameter(
|
|
'is_bookmark',
|
|
openapi.IN_QUERY,
|
|
description="Filter only bookmarked hadis for the authenticated user",
|
|
type=openapi.TYPE_BOOLEAN,
|
|
required=False,
|
|
default=False
|
|
),
|
|
openapi.Parameter(
|
|
'status',
|
|
openapi.IN_QUERY,
|
|
description="Filter hadis by status title. Case-insensitive partial matching.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
example="authentic"
|
|
),
|
|
openapi.Parameter(
|
|
'category',
|
|
openapi.IN_QUERY,
|
|
description="Filter hadis by category title. Case-insensitive partial matching.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
example="prayer"
|
|
),
|
|
openapi.Parameter(
|
|
'Accept-Language',
|
|
openapi.IN_HEADER,
|
|
description="Language code for localized content. Supported codes: 'en' (English), 'fa' (Persian), 'ar' (Arabic), 'ur' (Urdu), 'ru' (Russian). Defaults to 'en' if not specified.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
default='en',
|
|
enum=['en', 'fa', 'ar', 'ur', 'ru']
|
|
),
|
|
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(
|
|
'page_size',
|
|
openapi.IN_QUERY,
|
|
description="Number of items per page. If not provided, uses the default page size.",
|
|
type=openapi.TYPE_INTEGER,
|
|
required=False,
|
|
example=20
|
|
)
|
|
],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Successfully retrieved list of hadis with search results, categories, and statuses",
|
|
examples={
|
|
"application/json": {
|
|
"count": 150,
|
|
"next": "http://example.com/api/hadis/arguments/?page=2",
|
|
"previous": None,
|
|
"results": [
|
|
{
|
|
"id": 1,
|
|
"number": 1,
|
|
"slug": "intention-hadith",
|
|
"title": "The Opening Hadith on Intention",
|
|
"title_narrator": "From Umar ibn al-Khattab",
|
|
"text": "إنما الأعمال بالنيات وإنما لكل امرئ ما نوى",
|
|
"translation": "Actions are but by intention, and every man shall have only what he intended",
|
|
"category": {
|
|
"id": 1,
|
|
"title": "Faith Fundamentals",
|
|
"slug": "faith-fundamentals",
|
|
"source_type": "hadith",
|
|
"sect_type": "sunni"
|
|
},
|
|
"status": {
|
|
"id": 1,
|
|
"title": "Authentic (Sahih)",
|
|
"color": "green"
|
|
},
|
|
"share_link": "http://example.com/hadis/1"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"number": 2,
|
|
"slug": "prayer-timing",
|
|
"title": "Prayer Timing Importance",
|
|
"title_narrator": "From Abdullah ibn Mas'ud",
|
|
"text": "الصلاة على وقتها فريضة",
|
|
"translation": "Prayer at its proper time is obligatory",
|
|
"category": {
|
|
"id": 2,
|
|
"title": "Prayer Rites",
|
|
"slug": "prayer-rites",
|
|
"source_type": "hadith",
|
|
"sect_type": "sunni"
|
|
},
|
|
"status": {
|
|
"id": 1,
|
|
"title": "Authentic (Sahih)",
|
|
"color": "green"
|
|
},
|
|
"share_link": "http://example.com/hadis/2"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response(
|
|
description="Internal server error occurred while processing the request"
|
|
)
|
|
}
|
|
)
|
|
|
|
# # Swagger documentation for ContentReleaseSyncView
|
|
# content_release_sync_swagger = swagger_auto_schema(
|
|
# operation_description="Get list of all active content releases for offline mode sync",
|
|
# operation_summary="List Content Releases",
|
|
# tags=[
|
|
# 'Hadis'
|
|
# ],
|
|
# responses={
|
|
# status.HTTP_200_OK: openapi.Response(
|
|
# description="List of active content releases with pagination info",
|
|
# examples={
|
|
# "application/json": {
|
|
# "count": 2,
|
|
# "results": [
|
|
# {
|
|
# "id": 1,
|
|
# "version_name": "v1.2 - Muharram Update",
|
|
# "published_at": "2024-01-15T10:30:00Z",
|
|
# "description": "New hadis content added for Muharram month",
|
|
# "is_active": True
|
|
# },
|
|
# {
|
|
# "id": 2,
|
|
# "version_name": "v1.1 - Initial Release",
|
|
# "published_at": "2024-01-01T00:00:00Z",
|
|
# "description": "Initial release of the hadis database",
|
|
# "is_active": True
|
|
# }
|
|
# ]
|
|
# }
|
|
# }
|
|
# ),
|
|
# status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response(
|
|
# description="Internal server error"
|
|
# )
|
|
# }
|
|
# )
|
|
|
|
|
|
# Swagger documentation for ContentReleaseSyncView
|
|
content_release_sync_swagger = swagger_auto_schema(
|
|
operation_description='Get the latest active content release for offline mode sync',
|
|
operation_summary='Get Latest Content Release',
|
|
tags=['Dobodbi - Hadis'],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description='Latest active content release object',
|
|
examples={
|
|
'application/json': {
|
|
'id': 1,
|
|
'version_name': 'v1.2 - Muharram Update',
|
|
'published_at': '2024-01-15T10:30:00Z',
|
|
'description': 'New hadis content added for Muharram month',
|
|
'is_active': True
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response(
|
|
description='Internal server error'
|
|
)
|
|
}
|
|
)
|
|
|
|
|
|
# Swagger documentation for HadisCategoryXMindView
|
|
hadis_category_xmind_swagger = swagger_auto_schema(
|
|
operation_description="""
|
|
Retrieve a mind-map JSON structure (XMind format) for a specific category and its hadiths.
|
|
|
|
**Key Features:**
|
|
- Returns XMind-compatible JSON structure for mind-map visualization
|
|
- Root node represents the category
|
|
- Child nodes represent all hadiths in that category
|
|
- Supports multi-language content based on query parameter or Accept-Language header
|
|
- Includes bookmark status for each hadith (if user is authenticated)
|
|
- Returns all hadiths without pagination (suitable for mind-map visualization)
|
|
|
|
**Structure:**
|
|
- `rootTopic`: The main category node
|
|
- `id`: Category identifier (format: "cat-{category_id}")
|
|
- `title`: Localized category title
|
|
- `structureClass`: XMind structure type (org.xmind.ui.map.unbalanced for right-branching)
|
|
- `children.attached`: Array of hadith nodes
|
|
- Each hadith node contains:
|
|
- `id`: Hadith ID
|
|
- `slug`: URL-friendly identifier
|
|
- `title`: Localized hadith title
|
|
- `title_narrator`: Narrator information
|
|
- `text`: Original Arabic text
|
|
- `translation`: Translated text in requested language
|
|
- `share_link`: Direct link to the hadith
|
|
- `is_bookmarked`: Boolean indicating if user has bookmarked this hadith
|
|
|
|
**Usage:**
|
|
- Use this endpoint to generate mind-map visualizations of hadith categories
|
|
- The response format is compatible with XMind and similar mind-mapping tools
|
|
- Language can be specified via `?lang=` query parameter or Accept-Language header
|
|
- Bookmark status is only available for authenticated users
|
|
|
|
**Note:**
|
|
- This endpoint returns ALL hadiths in the category (no pagination)
|
|
- For categories with 1000+ hadiths, consider client-side limiting
|
|
- Only active (status=True) hadiths are included
|
|
""",
|
|
operation_summary="Get Category Mind-Map Structure (XMind Format)",
|
|
tags=['Dobodbi - Hadis'],
|
|
manual_parameters=[
|
|
openapi.Parameter(
|
|
'category_slug',
|
|
openapi.IN_PATH,
|
|
description="Unique slug identifier of the Hadis category. Must be a valid category slug that exists in the system.",
|
|
type=openapi.TYPE_STRING,
|
|
required=True,
|
|
example='cat-l3-25-7f5bcb'
|
|
),
|
|
openapi.Parameter(
|
|
'lang',
|
|
openapi.IN_QUERY,
|
|
description="Language code for content localization. Supported codes: 'en' (English), 'fa' (Persian), 'ar' (Arabic), 'ur' (Urdu), 'ru' (Russian). Defaults to 'en' if not specified. Can also be set via Accept-Language header.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
default='en',
|
|
enum=['en', 'fa', 'ar', 'ur', 'ru']
|
|
),
|
|
openapi.Parameter(
|
|
'Accept-Language',
|
|
openapi.IN_HEADER,
|
|
description="Alternative way to specify language code. If both query parameter and header are provided, query parameter takes precedence.",
|
|
type=openapi.TYPE_STRING,
|
|
required=False,
|
|
default='en',
|
|
enum=['en', 'fa', 'ar', 'ur', 'ru']
|
|
)
|
|
],
|
|
responses={
|
|
status.HTTP_200_OK: openapi.Response(
|
|
description="Successfully retrieved mind-map structure for the specified category",
|
|
examples={
|
|
"application/json": {
|
|
"rootTopic": {
|
|
"id": "cat-25",
|
|
"title": "Book of Faith",
|
|
"structureClass": "org.xmind.ui.map.unbalanced",
|
|
"children": {
|
|
"attached": [
|
|
{
|
|
"id": 1,
|
|
"slug": "hadis-intention-and-actions",
|
|
"title": "The Intention",
|
|
"title_narrator": "From Umar ibn al-Khattab",
|
|
"text": "إنما الأعمال بالنيات وإنما لكل امرئ ما نوى",
|
|
"translation": "Actions are but by intention, and every man shall have only what he intended",
|
|
"share_link": "http://example.com/hadis/hadis-intention-and-actions",
|
|
"is_bookmarked": False
|
|
},
|
|
{
|
|
"id": 2,
|
|
"slug": "hadis-gabriel-hadith",
|
|
"title": "The Hadith of Gabriel",
|
|
"title_narrator": "From Abu Hurairah",
|
|
"text": "بينما نحن عند رسول الله صلى الله عليه وسلم ذات يوم",
|
|
"translation": "While we were sitting with the Messenger of Allah (peace be upon him) one day",
|
|
"share_link": "http://example.com/hadis/hadis-gabriel-hadith",
|
|
"is_bookmarked": True
|
|
},
|
|
{
|
|
"id": 3,
|
|
"slug": "hadis-islam-faith-excellence",
|
|
"title": "Islam, Faith, and Excellence",
|
|
"title_narrator": "From Abu Hurairah",
|
|
"text": "عن أبي هريرة رضي الله عنه قال: قال رسول الله صلى الله عليه وسلم",
|
|
"translation": "Narrated Abu Hurairah: The Messenger of Allah (peace be upon him) said",
|
|
"share_link": "http://example.com/hadis/hadis-islam-faith-excellence",
|
|
"is_bookmarked": False
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_404_NOT_FOUND: openapi.Response(
|
|
description="Category not found. The provided category_slug does not exist in the system.",
|
|
examples={
|
|
"application/json": {
|
|
"detail": "Not found."
|
|
}
|
|
}
|
|
),
|
|
status.HTTP_500_INTERNAL_SERVER_ERROR: openapi.Response(
|
|
description="Internal server error"
|
|
)
|
|
}
|
|
)
|