[codex] Fix content API v4 doc parity and add Quran Reflect 200 examples#112
Merged
[codex] Fix content API v4 doc parity and add Quran Reflect 200 examples#112
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Content API v4 OpenAPI “source of truth” and regenerates the Docusaurus OpenAPI docs to bring published contracts back in parity with the actual API surface, including adding complete 200-response examples for Quran Reflect read endpoints.
Changes:
- Regenerated current and v4.0.0 versioned Content API docs/sidebars to reflect updated v4 spec parity.
- Added alias-route documentation entries for Rub el Hizb endpoint families (recitations/tafsirs/etc.).
- Added concrete
200response examples for Quran Reflect comments endpoints in the generated docs.
Reviewed changes
Copilot reviewed 15 out of 125 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/content_apis_versioned/sidebar.js | Regenerated current docs sidebar; includes new alias-route doc entries. |
| docs/content_apis_versioned/posts-controller-get-comments.api.mdx | Adds/updates 200 response example content for “Get post comments”. |
| docs/content_apis_versioned/posts-controller-get-all-comment.api.mdx | Adds/updates 200 response example content for “Get all post comments”. |
| docs/content_apis_versioned/list-rub-el-hizb-tafsirs-rub.api.mdx | New alias-route doc page for rub-el-hizb tafsirs endpoint variant. |
| docs/content_apis_versioned/list-rub-el-hizb-recitation-rub-el-hizb.api.mdx | New alias-route doc page for rub-el-hizb recitation endpoint variant. |
| docs/content_apis_versioned/4.0.0/sidebar.js | Regenerated v4.0.0 sidebar; includes new alias-route doc entries. |
| docs/content_apis_versioned/4.0.0/posts-controller-get-comments.api.mdx | Adds/updates 200 response example content for “Get post comments” (v4.0.0 docs). |
| docs/content_apis_versioned/4.0.0/posts-controller-get-all-comment.api.mdx | Adds/updates 200 response example content for “Get all post comments” (v4.0.0 docs). |
| docs/content_apis_versioned/4.0.0/list-rub-el-hizb-tafsirs-rub.api.mdx | New alias-route doc page for rub-el-hizb tafsirs endpoint variant (v4.0.0 docs). |
| docs/content_apis_versioned/4.0.0/list-rub-el-hizb-recitation-rub-el-hizb.api.mdx | New alias-route doc page for rub-el-hizb recitation endpoint variant (v4.0.0 docs). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Deploying qf-api-docs with
|
| Latest commit: |
8a85934
|
| Status: | ⚡️ Build in progress... |
…rity # Conflicts: # docs/content_apis_versioned/4.0.0/posts-controller-feed.api.mdx # docs/content_apis_versioned/posts-controller-feed.api.mdx
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
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.
Summary
This PR updates the content API v4 OpenAPI source of truth and regenerates the content docs to match the actual API surface.
The work comes from a full static audit of
openAPI/content/v4.jsonagainstquran.com-api, plus Quran Reflect read-endpoint response shapes fromquran.com-users-backend.Why
The audit found multiple contract mismatches between the published content API docs and the implementation, including:
/quran/verses/{script}/quran/translations/{translation_id}Because the generated docs are driven from
v4.json, the fixes needed to happen at the spec level and then be regenerated into both current and versioned content docs.What Changed
OpenAPI parity fixes
Updated
openAPI/content/v4.jsonso the documented contracts now match the API implementation for:/resources/recitations/resources/languages/resources/chapter_reciters/resources/chapter_infos/resources/translations/{translation_id}/info/resources/recitations/{recitation_id}/info/quran/translations/{translation_id}/quran/verses/{script}and the explicit script endpointsFamily-level normalization
Standardized and corrected shared content API docs by:
rub_numberwithrub_el_hizb_numberin the relevant shared schemas/examplesper_page,current_page,next_page,total_pages, andtotal_recordsfields,page, andper_pageparams where supported across translations, tafsirs, and recitationschapter_recitationspath params to usereciter_idlanguagequery param from the chapter recitation list endpointQuran Reflect coverage
Added full
200response schemas and examples for all five Quran Reflect endpoints included in this spec:/quran-reflect/v1/posts/feed/quran-reflect/v1/posts/{id}/quran-reflect/v1/posts/user-posts/{id}/quran-reflect/v1/posts/{id}/comments/quran-reflect/v1/posts/{id}/all-commentsThese response shapes were mirrored from
quran.com-users-backend.Generated docs
Regenerated:
docs/content_apis_versioned/*docs/content_apis_versioned/4.0.0/*Impact
Validation
Ran successfully:
yarn postgen-api-sidebarsyarn buildThe docs build completed successfully after regeneration, which confirms the updated spec renders cleanly through the docs pipeline.