Migrate and Modernize SDK Documentation for Quran Foundation API#12
Closed
basit3407 wants to merge 32 commits intoquran:mainfrom
Closed
Migrate and Modernize SDK Documentation for Quran Foundation API#12basit3407 wants to merge 32 commits intoquran:mainfrom
basit3407 wants to merge 32 commits intoquran:mainfrom
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 ↗︎
|
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR migrates and modernizes the JavaScript SDK documentation for the Quran Foundation API, updating it from the previous api-js SDK to reflect the new API structure and OAuth2 authentication requirements.
- Adds complete SDK documentation section with authentication, usage examples, and migration guide
- Updates navigation configuration to include SDK documentation in both sidebar and main navigation
- Provides comprehensive examples for all major SDK functionality including chapters, verses, audio, resources, and search
Reviewed Changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| sidebars.js | Adds SDK category to sidebar with authentication, usage, endpoints, and migration pages |
| docusaurus.config.js | Adds SDK navigation item to main navbar |
| docs/sdk/index.md | Provides SDK overview with installation instructions and basic setup |
| docs/sdk/authentication.md | Explains OAuth2 authentication flow and token management |
| docs/sdk/usage.md | Comprehensive usage examples for all SDK methods and utilities |
| docs/sdk/endpoints.md | Reference guide linking to official API documentation |
| docs/sdk/migration.md | Migration guide for users upgrading from the old QuranJS API |
| const random = await quran.qf.verses.findRandom(); | ||
| ``` | ||
|
|
||
| Additional helpers include `findByPage`, `findByJuz`, `findByHizb` and `findByRub`. |
There was a problem hiding this comment.
[nitpick] Missing comma before 'and' in the list. Should be: 'Additional helpers include findByPage, findByJuz, findByHizb, and findByRub.'
Suggested change
| Additional helpers include `findByPage`, `findByJuz`, `findByHizb` and `findByRub`. | |
| Additional helpers include `findByPage`, `findByJuz`, `findByHizb`, and `findByRub`. |
|
|
||
| If you previously used the `@quranjs/api` SDK against the Quran.com endpoints, switching to the new Quran Foundation API requires a few changes. | ||
|
|
||
| 1. **Base URLs** – The new SDK defaults to `https://apis.quran.foundation` and `https://oauth2.quran.foundation`. Remove any overrides pointing to quran.com. |
There was a problem hiding this comment.
The migration guide should provide specific examples of how to update existing code rather than just describing what needs to change. Consider adding before/after code examples for common migration scenarios.
Suggested change
| 1. **Base URLs** – The new SDK defaults to `https://apis.quran.foundation` and `https://oauth2.quran.foundation`. Remove any overrides pointing to quran.com. | |
| 1. **Base URLs** – The new SDK defaults to `https://apis.quran.foundation` and `https://oauth2.quran.foundation`. Remove any overrides pointing to quran.com. | |
| **Before:** | |
| ```javascript | |
| const api = require('@quranjs/api'); | |
| api.configure({ | |
| baseUrl: 'https://api.quran.com', | |
| }); |
After:
const api = require('@quran.foundation/api');
api.configure({
baseUrl: 'https://apis.quran.foundation',
});
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.
This PR migrates the documentation from the previous SDK (
api-js) and updates it for the Quran Foundation Content API.Key changes:
/docsto reflect the new API structure and authentication (OAuth2)Please review and let me know if any further updates are needed!