feat(docs): embed markdown guides in Scalar API reference#3453
feat(docs): embed markdown guides in Scalar API reference#3453PierreBrisorgueil merged 3 commits intomasterfrom
Conversation
Add support for per-module markdown guides discovered via `modules/*/doc/guides/*.md` globbing. Guides are merged into the OpenAPI spec's `info.description` so Scalar renders them as sidebar sections alongside the API reference. Migrates the 3 guides previously shipped by the Vue docs module (getting-started, authentication, organizations) under `modules/core/doc/guides/` so they are always active regardless of downstream project configuration. Closes #3451
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 13 minutes and 34 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (6)
WalkthroughThe changes implement a markdown guide loading system that discovers guide files from Changes
Sequence Diagram(s)sequenceDiagram
participant Express Server
participant Config
participant Guides Helper
participant OpenAPI Spec
participant Scalar Frontend
Express Server->>Config: Load configuration with assets glob
Config->>Config: Glob modules/*/doc/guides/*.md
Config->>Guides Helper: Initialize with guide file paths
Guides Helper->>Guides Helper: Load each guide file (with error handling)
Guides Helper->>Guides Helper: Strip H1 headers, derive titles, sort alphabetically
Guides Helper->>OpenAPI Spec: Merge guides into info.description
OpenAPI Spec->>OpenAPI Spec: Append guide titles and bodies with separators
Express Server->>Express Server: Serve merged spec at /api/spec.json
Scalar Frontend->>Express Server: Request spec
Express Server->>Scalar Frontend: Return spec with embedded guides
Scalar Frontend->>Scalar Frontend: Render guides in sidebar alongside OpenAPI reference
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3453 +/- ##
==========================================
+ Coverage 85.58% 85.73% +0.15%
==========================================
Files 113 114 +1
Lines 2878 2910 +32
Branches 796 804 +8
==========================================
+ Hits 2463 2495 +32
Misses 329 329
Partials 86 86 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Adds support for embedding per-module markdown guides into the OpenAPI spec so Scalar (/api/docs) can render long-form documentation alongside the API reference, and migrates initial core guides into the Node backend.
Changes:
- Add a new
lib/helpers/guides.jshelper to load/sort markdown guides and merge them intospec.info.description. - Extend config assets + global file discovery to include
modules/*/doc/guides/*.md, and wire guide merging intoinitSwagger. - Add unit tests covering guide loading/merging and swagger serving behavior, and introduce three starter guides under
modules/core/doc/guides/.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
modules/core/tests/core.unit.tests.js |
Adds tests for guide helper behavior and for swagger spec serving with merged guides. |
modules/core/doc/guides/authentication.md |
New authentication guide content intended for Scalar sidebar. |
modules/core/doc/guides/getting-started.md |
New getting-started guide content intended for Scalar sidebar. |
modules/core/doc/guides/organizations.md |
New organizations guide content intended for Scalar sidebar. |
lib/services/express.js |
Loads guides from config.files.guides and merges into the served OpenAPI spec. |
lib/helpers/guides.js |
New helper to load/normalize markdown guides and append them to info.description. |
lib/helpers/config.js |
Adds files.guides discovery via assets.allGuides. |
config/assets.js |
Introduces allGuides glob pattern for guide discovery. |
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
- Auth guide uses cookie-based JWT (TOKEN cookie), no refresh token - Fix password reset payload (newPassword instead of password) - Organizations: /invites route and currentOrganization + /switch (not the X-Organization-Id header) - getting-started prerequisite bumped to Node 22+ - Include guides in module-activation filtering (fileKeys) - Expand initGlobalConfigFiles JSDoc
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
lib/helpers/config.js (1)
141-155: 🛠️ Refactor suggestion | 🟠 MajorAdd full JSDoc tags to modified
initGlobalConfigFiles.Line 144 modifies
initGlobalConfigFiles, but its header is missing@paramand@returns.✍️ Proposed doc-only fix
/** - * Initialize global configuration files + * Initialize global configuration files. + * `@param` {object} assets - Glob patterns configuration from `config/assets.js`. + * `@returns` {Promise<object>} Resolved file groups keyed by asset type. */ const initGlobalConfigFiles = async (assets) => {As per coding guidelines:
**/*.js: Every new or modified function must have a JSDoc header: one-line description,@paramfor each argument,@returnsfor any non-void return value.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@lib/helpers/config.js` around lines 141 - 155, The function initGlobalConfigFiles is missing a JSDoc header; add a one-line description plus JSDoc tags: include `@param` {Object} assets - input asset globs (describe keys like allYaml, allGuides, mongooseModels, preRoutes, routes, config, policies) and `@returns` {Promise<Object>} - resolved object containing swagger, guides, mongooseModels, preRoutes, routes, configs, and policies; place this JSDoc immediately above the initGlobalConfigFiles declaration so it documents that function and its return value.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@modules/core/tests/core.unit.tests.js`:
- Around line 613-632: Add an integration test in
modules/core/tests/core.integration.tests.js that boots the app (or http server)
and verifies the expressService.initSwagger behavior end-to-end: send an HTTP
GET to /api/spec.json and assert the returned JSON has info.description as a
string that contains the rendered guide content (e.g., '# Getting Started' and
'Your first API call'), and also hit /api/docs to ensure the docs endpoint is
reachable; reuse the same fixtures/paths used in the unit test and ensure the
app is started/stopped within the test lifecycle so the guide merge behavior
exercised by expressService.initSwagger is validated in an integration scenario.
---
Outside diff comments:
In `@lib/helpers/config.js`:
- Around line 141-155: The function initGlobalConfigFiles is missing a JSDoc
header; add a one-line description plus JSDoc tags: include `@param` {Object}
assets - input asset globs (describe keys like allYaml, allGuides,
mongooseModels, preRoutes, routes, config, policies) and `@returns`
{Promise<Object>} - resolved object containing swagger, guides, mongooseModels,
preRoutes, routes, configs, and policies; place this JSDoc immediately above the
initGlobalConfigFiles declaration so it documents that function and its return
value.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: fe808fb9-edf7-470f-8061-fc903add330f
📒 Files selected for processing (8)
config/assets.jslib/helpers/config.jslib/helpers/guides.jslib/services/express.jsmodules/core/doc/guides/authentication.mdmodules/core/doc/guides/getting-started.mdmodules/core/doc/guides/organizations.mdmodules/core/tests/core.unit.tests.js
- Verify /api/spec.json exposes merged markdown guides in info.description (Getting Started, Authentication, Organizations) - Verify /api/docs serves the Scalar HTML reference page
Summary
modules/*/doc/guides/*.md, merged into the OpenAPI spec'sinfo.descriptionso Scalar renders them in its sidebar next to the API reference. Migrated the 3 guides previously shipped by the Vuedocsmodule (getting-started, authentication, organizations) intomodules/core/doc/guides/.Scope
core(guides),lib/helpers/guides.js,lib/services/express.js,config/assets.jsnone— guides are discovered by glob, any module can drop adoc/guides/*.mdfile and it will appearlow— purely additive, only affects/api/docsrenderingMerge approach
Scalar renders the OpenAPI
info.descriptionas an "Introduction" section and splits on markdown H1/H2 for sidebar navigation. Each loaded guide is injected as a top-level# Titleblock intoinfo.description, so each guide becomes its own sidebar entry. Guides are:allGuidesasset pattern (modules/*/doc/guides/*.md)info.description, preserving any existing intro textPlaced the migrated guides under
modules/core/doc/guides/so they are always active regardless of downstream module activation (core is never filtered out).Validation
npm run lintnpm run test:coverage— 763/763 tests pass,lib/helpers/guides.jsat 100% linesinitSwaggertest verifies guides are merged into the served spec via/api/spec.jsonGuardrails check
Notes for reviewers
modules/{name}/doc/guides/foo.mdfile automatically makes "Foo" appear in the Scalar sidebar on next restart — no registration neededdocsmodule is handled in a separate PRSummary by CodeRabbit