[codex] Document v4 chapter info resource support

[basit3407]

Summary

• document the new resource-aware v4 chapter-info query params and response fields in openAPI/content/v4.json
• update the rendered current and 4.0.0 chapter-info docs pages to match the source contract
• add explicit guidance for author-specific surah info, including Ibn Ashur, and update request examples to show resource_id and include_resources
• clarify that chapter_info can be null when a requested resource does not resolve for the resolved language

Why

The backend now supports qdc-style resource-aware chapter info in v4, so the published docs need to describe resource_id, include_resources, chapter_info.resource_id, resources, and how to use the endpoint for specific authors such as Ibn Ashur.

Impact

• docs consumers can discover how to request author-specific chapter info via v4
• the chapter-info contract is aligned across the source OpenAPI spec and the rendered docs pages
• request examples now show the resource-aware query shape instead of the old language-only shape

Validation

• ruby -rjson -e 'JSON.parse(File.read(%q{openAPI/content/v4.json}))'
• npx docusaurus build

[cloudflare-workers-and-pages]

Deploying qf-api-docs with    Cloudflare Pages

Latest commit:	a91fa9e
Status:	✅  Deploy successful!
Preview URL:	https://c20f2b8e.qf-api-docs.pages.dev
Branch Preview URL:	https://codex-v4-chapter-info-docs.qf-api-docs.pages.dev

View logs

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/quran/qf-api-docs/blob/b1e39cb86e0d66af379c6192ce11bcb1464068b0/openAPI/content/v4.json#L15585-L15589
Remove stray '=' from pagination response field names

The pagination schema now documents total_pages= and total_records= as response keys, but the API contract and prior docs use total_pages/total_records. This will propagate incorrect field names into generated SDKs/docs and cause consumers to miss pagination metadata when parsing real responses.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[basit3407]

Addressed the Codex feedback in ec70c2a. openAPI/content/v4.json now uses the correct pagination field names, total_pages and total_records, in both the schema and the example payload. This comment was posted as a top-level PR conversation comment rather than a review thread, so there is nothing resolvable to mark resolved in GitHub for it.

[basit3407]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/quran/qf-api-docs/blob/ec70c2a9fb4501086dacd2bc2cd0c1ba4e0e062d/openAPI/content/v4.json#L15255
Keep verse rub field consistent with published payloads

The verse schema now defines rub_number, but the same component example (and many operation examples in this spec) still use rub_el_hizb_number, so the contract is internally inconsistent. This can break generated clients/validators that trust the schema and then fail to map documented response payloads unless every backend payload was renamed at the same time.

---

https://github.com/quran/qf-api-docs/blob/ec70c2a9fb4501086dacd2bc2cd0c1ba4e0e062d/openAPI/content/v4.json#L15588-L15590
Preserve nullable next_page in pagination schema

The shared pagination.next_page field is now a non-null integer, but this spec still includes response examples with next_page: null for terminal pages (e.g., around line 3713). Removing nullability makes valid last-page payloads fail schema validation and can cause generated SDK validators to reject real responses.

---

https://github.com/quran/qf-api-docs/blob/ec70c2a9fb4501086dacd2bc2cd0c1ba4e0e062d/openAPI/content/v4.json#L16749-L16751
Use a numeric example for comment totals

PostAllCommentsResponse.total is declared as number, but its example was changed to a string ("10 // works also with swagger setup"). This violates the schema and can break OpenAPI tooling that validates examples or uses them to generate typed sample code.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[basit3407]

Addressed the three Codex findings in 3660d0b.

1. rub_number vs rub_el_hizb_number
   Fixed the shared verse schema back to rub_el_hizb_number and also fixed the matching regression in the shared translation schema so the schema and examples are consistent with the published payload shape.

2. pagination.next_page nullability
   Restored nullable: true on the shared pagination schema so terminal-page examples with next_page: null remain valid.

3. PostAllCommentsResponse.total example type
   Changed the example from a string to the numeric value 10 so it matches the declared schema type.

I also re-generated the content API docs from the corrected openAPI/content/v4.json and verified the docs build locally.

These Codex notes were posted as top-level PR conversation comments rather than review threads, so GitHub does not provide a per-comment resolve action or threaded inline reply target for them.

[basit3407]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/quran/qf-api-docs/blob/3660d0b6b578d4851a1be3c86eca2a024b92f4ee/openAPI/content/v4.json#L8838-L8841
Keep info field in recitation info response schema

The 200 response schema for /resources/recitations/{recitation_id}/info now documents info objects with only id, but the same example in this operation still returns info.info (nullable text). This introduces a contract mismatch that will cause generated clients/types from OpenAPI to drop the actual recitation info payload even though the endpoint description and example still expose it.

---

https://github.com/quran/qf-api-docs/blob/3660d0b6b578d4851a1be3c86eca2a024b92f4ee/openAPI/content/v4.json#L8968-L8971
Keep info field in translation info response schema

The 200 response schema for /resources/translations/{translation_id}/info was reduced to only info.id, while its example still includes info.info. This mismatch makes the published OpenAPI contract inaccurate and can break downstream SDK/type generation by omitting the translation metadata text field clients expect from this endpoint.

---

https://github.com/quran/qf-api-docs/blob/3660d0b6b578d4851a1be3c86eca2a024b92f4ee/openAPI/content/v4.json#L9773-L9777
Restore slug in chapter_infos item schema

In /resources/chapter_infos, the item schema no longer declares slug even though the response example for the same operation still includes it and the chapter-info flow now relies on discovering resources by id or slug. This inconsistency will hide slug from OpenAPI-derived clients despite it being part of documented responses.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[basit3407]

Addressed the latest Codex review in 4c9c6e4.

1. Recitation info schema
   Restored the nullable info field under /resources/recitations/{recitation_id}/info in openAPI/content/v4.json so the schema matches both the example payload and the backend contract.

2. Translation info schema
   Restored the nullable info field under /resources/translations/{translation_id}/info for the same reason.

3. /resources/chapter_infos slug
   No code change for this one. I re-checked the current branch and slug is already present in the item schema for /resources/chapter_infos, including both required and properties, so that specific comment does not appear actionable on 4c9c6e4.

I also regenerated the two affected content API pages (recitation-info and translation-info) and verified both JSON.parse(openAPI/content/v4.json) and a local Docusaurus production build.

[basit3407]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/quran/qf-api-docs/blob/4c9c6e490135ff38544bc78f22e522b3143e2cce/openAPI/content/v4.json#L15197-L15199
Align translation example fields with schema

The translation schema example now includes ruku_number, manzil_number, and a tafsir-style slug, but those fields are no longer declared in components.schemas.translation. This makes the OpenAPI contract self-contradictory for translation responses, so generated SDKs and docs consumers can disagree on which fields are actually supported. Please make the schema and example consistent (either restore the properties or remove/correct the extra example keys).

---

https://github.com/quran/qf-api-docs/blob/4c9c6e490135ff38544bc78f22e522b3143e2cce/openAPI/content/v4.json#L6721-L6724
Correct translation path parameter description

The translation_id path parameter for GET /quran/translations/{translation_id} is documented as Recitation id, which is a resource mismatch and can mislead users into supplying the wrong identifier context. The parameter description should refer to translation resources to match the endpoint semantics.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[basit3407]

Addressed the first Codex note in commit 25c12fc.

I removed ruku_number, manzil_number, and slug from the translation example in openAPI/content/v4.json so the example matches the current translation schema and the backend oas.yaml contract.

Validation:

• ruby -rjson -e "JSON.parse(File.read(%q{openAPI/content/v4.json}))"
• node_modules/.bin/docusaurus.cmd build

There is no resolve action available for this specific Codex note because it is a top-level PR conversation comment, not a GitHub review thread.

[basit3407]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/quran/qf-api-docs/blob/25c12fc07b2cd40a0c7293edfaa04a39ae7ad4a1/openAPI/content/v4.json#L14334-L14338
Restore filter[] query names for Quran Reflect feed

This changes /quran-reflect/v1/posts/feed from the established filter[...] query contract to bare keys like authors, tags, and references, which will cause generated clients to send different parameter names and lose server-side filtering behavior. The same feed endpoint in openAPI/user-related-apis/v1.json still uses filter[authors], filter[tags], and indexed filter[references][0][...], so this introduces a cross-spec contract mismatch for the same gateway route.

---

https://github.com/quran/qf-api-docs/blob/25c12fc07b2cd40a0c7293edfaa04a39ae7ad4a1/openAPI/content/v4.json#L8018-L8022
Re-add pagination/fields params on by_ content endpoints*

The parameter list is now closed after path params, dropping query controls like fields, page, and per_page from paginated by_* endpoints (for example this recitations-by-juz route, and similarly across recitations/tafsirs/translations). That regresses the OpenAPI contract used for docs/SDK generation: consumers can no longer discover or type these inputs even though the response schema still includes pagination metadata, so clients lose the ability to request specific fields or pages.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[basit3407]

Addressed the two latest Codex notes in commit a91fa9e.

1. Quran Reflect feed query contract
   openAPI/content/v4.json now documents /quran-reflect/v1/posts/feed with the established filter[...] parameter names again (filter[authors], filter[tags], indexed filter[references][0][...], filter[groups], filter[pages], filter[postTypeIds], filter[tagsOperator], filter[referencesOperator], filter[verifiedOnly]).

2. by_* content endpoint query controls
   Restored the missing fields, page, and per_page query params on the existing recitations, translations, and tafsirs by_* endpoints in this spec so the generated docs match the established contract again.

I regenerated the content API docs from the updated openAPI/content/v4.json and verified both:

• ruby -rjson -e "JSON.parse(File.read(%q{openAPI/content/v4.json}))"
• node_modules/.bin/docusaurus.cmd build

These Codex notes are still top-level PR conversation comments rather than GitHub review threads, so there is no resolve action available for them.

[basit3407]

Superseded by #118. This replacement was rebuilt from a fresh origin/main worktree and keeps only the chapter-info docs changes.