📚 Sync docs: Fix Tafsir endpoint schema & document random verse filters & other updates

[basit3407]

This PR includes the following 5 important documentation updates:

Fix incorrect response schema for /tafsirs/{resource_id}/by_ayah/{ayah_key}

• Fixed schema in `v4.json.
• Removed the manually written MDX file.
• Regenerated docs using yarn clean-all && yarn gen-all && yarn start.
• Verified that the auto-generated docs now render correctly and show the accurate response schema.

Add missing query filters for the Random Verse endpoint

• Documented existing support for location-based filters:

  • chapter_number, page_number, juz_number, hizb_number, rub_el_hizb_number, ruku_number, manzil_number

• These were already available in the API but not listed in the docs.

✏️ Chore: Fix minor typos in v4.json

• Fixed minor schema typos in the OpenAPI definition file
• Re-ran code generation commands to regenerate API docs

🧹 Fix: Replace unrendered model placeholders

• Replaced #model:... tokens with proper model names in endpoint titles
• Fixes display issues in autogenerated docs where model references were not resolving

🔗 Fix: Replace unresolved endpoint tokens

• Replaced placeholder tokens like #endpoint:HLbauN2sdGitPQPPL with actual endpoint URLs or names
• Ensures endpoint references in the docs are correctly rendered and navigable

This sync ensures the docs accurately reflect both frontend rendering stability and full API filtering capabilities.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
qf-api-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 25, 2025 5:48am

[Copilot]

Pull Request Overview

This PR updates the API documentation to correctly reflect the current behavior of two endpoints. The changes include:

• Updating the OpenAPI schema for the tafsir endpoint by replacing the auto‐generated array ("tafsirs") with a manually written object ("tafsir") and its required properties.
• Adding and documenting new query parameters (e.g. chapter_number, page_number, etc.) for the Random Verse endpoint.
• Updating the MDX documentation files for both endpoints to align with the latest API design and improve error response clarity.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
openAPI/content/v4.json	Revised response schema for the tafsir endpoint and added new query parameters.
docs/content_apis_versioned/random-verse.api.mdx	Included additional query parameters for the Random Verse endpoint and updated docs.
docs/content_apis_versioned/list-ayah-tafsirs.api.mdx	Updated the tafsir endpoint documentation to reflect the new response format and error descriptions.

Comments suppressed due to low confidence (3)

openAPI/content/v4.json:1504

• Ensure that changing the response field from an array ('tafsirs') to an object ('tafsir') is fully consistent with the API implementation, as this modification constitutes a breaking change for clients expecting an array.

          {

docs/content_apis_versioned/random-verse.api.mdx:13

• [nitpick] Confirm that numeric ranges use consistent formatting (e.g. en-dashes) across all query parameter descriptions for clarity and consistency.

    "description":"Return a random verse only from the specified Muṣḥaf page (1–604).",

docs/content_apis_versioned/list-ayah-tafsirs.api.mdx:109

• Verify that the updated error descriptions for status codes 403 and 404 accurately reflect the backend responses (e.g. 403 for expired tokens or insufficient scopes, and 404 for missing resources).

<TabItem value="403">

[osamasayed]

Changing the content of an mdx file manually that is a result of parsing .json OpenAPI schema (openAPI/content/v4.json) risks being overridden (using yarn clean-all && yarn gen-all && yarn start). The source of truth should be the json file itself.

[basit3407]

Thanks for flagging that — you were absolutely right.

The issue wasn’t with the v4.json itself (it already had the correct schema and example), but I had manually written an MDX file earlier to bypass the crash. After your comment, I deleted the manual MDX and re-ran:

yarn clean-all && yarn gen-all && yarn start

The page now renders correctly from the auto-generated docs, fully schema-driven as intended. Appreciate the catch ✅