📘 Docs: Add auto-translate warning + OpenAPI fixes for audio endpoints (document segments=true; correct List Surah Recitation schema)#13
Merged
osamasayed merged 42 commits intoquran:mainfrom Sep 10, 2025
Conversation
in random verse endpoint Added missing documentation for existing query parameters supported by the random verse endpoint: - chapter_number - page_number - juz_number - hizb_number - rub_el_hizb_number - ruku_number - manzil_number These parameters were already supported in the API but not reflected in the documentation. This update ensures developers are aware of all available filtering options when using the endpoint.
/tafsirs/{resource_id}/by_ayah/{ayah_key}
Fixed the incorrect response schema shown for the /tafsirs/{resource_id}/by_ayah/{ayah_key} endpoint in the docs.
The autogenerated version via <ApiTabs> was causing runtime crashes due to unresolved OpenAPI store references. Since that approach wasn't working despite correct infoPath and operationId setup, we manually wrote the MDX documentation using standard Docusaurus components.
Tested locally – page now renders successfully and reflects the accurate response structure.
list-ayah-tafsirs and regenerate MDX
Updated the OpenAPI schema (v4.json) for the /tafsirs/{resource_id}/by_ayah/{ayah_key} endpoint to ensure the response structure reflects the actual API output.
The previous crash with <ApiTabs> was due to incorrect or incomplete schema context. After fixing the schema, we ran:
- yarn clean-all
- yarn gen-all
- yarn start
The generated docs now render correctly and reflect the accurate response, eliminating the need for manual overrides.
Fix additional v4 typos
…haf--in-v4.json Fix Mushaf typo
…aceholders-in-v4.json Fix unrendered model placeholders
tokens with actual endpoints
…-tokens-in-v4.json Fix placeholder endpoints
…in-get-todays-plan-api Fix mushafId param docs
…fields-and-word_fields Add field reference documentation and links
…g-other-endpoints docs: link resource references
…ation-for-docusaurus Add JavaScript SDK docs
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
…in v4.json (param, schema, and examples)
…mestamps; correct schema & examples)
basit3407
changed the title
osamasayed
approved these changes
Sep 10, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR now includes two documentation updates:
Auto-translate warning (content docs)
OpenAPI spec corrections (used by Docusaurus)
File:
v4.json(OpenAPI 3.x). No MDX changes; docs will be regenerated from this file.Endpoint: Chapter Reciter Audio File (
/docs/content_apis_versioned/chapter-reciter-audio-file)segments: boolean(defaultfalse).200response schema to includetimestamps[]with optionalsegmentswhensegments=true.timestamps+segments).SegmentTriplet,VerseTimestamp,AudioFile,ChapterReciterAudioFileResponse).Endpoint: List Surah Recitation (
/docs/content_apis_versioned/list-surah-recitation)Remove any mention of
segments(param or field).Ensure response is:
{ "audio_files": [{ "verse_key": "1:1", "url": "Alafasy/mp3/001001.mp3" }, ...], "pagination": { "per_page": 10, "current_page": 1, "next_page": null, "total_pages": 1, "total_records": 7 } }Replace incorrect schema/examples that showed
timestamps/segmentswith the correct ones above.Keep/standardize the
Paginationschema.Why
segments=truebehavior or showed fields that the API doesn’t return for List Surah Recitation.Backward compatibility
segmentsis optional; default behavior is unchanged.segments).How to review
Review
v4.jsondiff only.Rebuild docs from
v4.jsonand verify:segmentsparam.{ verse_key, url }pluspagination(notimestamps/segments).Release notes
segments=truefor Chapter Reciter Audio File; fix List Surah Recitation schema/examples to removesegments.