docs(recipe): add NestJS + Swagger OpenAPI merge guide

[lsmith77]

What

Extends the NestJS recipe (docs/recipe/nestjs.md) with two patterns for going beyond the basic catch-all handler, both drawn from a production ZenStack 3.x + NestJS app.

Sharing the handler across thin controllers

Wrapping RestApiHandler in a service and forwarding from small, per-resource controllers, so guards, interceptors, rate limits, and Swagger decorators attach per resource while the delegation logic stays in one place.

Merging the OpenAPI spec with @nestjs/swagger

A single Swagger UI that documents both the handler's schema-generated endpoints and hand-written NestJS controllers. Covers the two things that actually trip people up:

• Path prefixes differ — ZenStack paths are relative to the handler's endpoint (/post/{id}); NestJS paths carry the global prefix (/api/post/{id}). The helper re-prefixes ZenStack paths before merging.
• Both contribute components — merge paths (NestJS operation wins on conflict) and union components.schemas.

Uses generateSpec({ respectAccessPolicies: true }) so the published spec matches what the API actually exposes, and closes with a "going further" tip pointing at response-header merging, public/internal filtering, and schema pruning.

Why

The existing recipe stops at the @All('/*path') catch-all. There was no guidance on producing unified OpenAPI docs when a real app mixes schema-generated CRUD with custom NestJS endpoints — a common need, and easy to get the path-prefix/component merge subtly wrong.

Open question: should some of this become shared code?

Parts of what this recipe documents by hand are generic enough to package, and I'd value maintainer input on whether/where that should land. The candidates split along a dependency line:

• Framework-agnostic OpenAPI post-processing (no @nestjs/* deps) — pruneUnreferencedSchemas (BFS over $ref chains to drop unreachable components.schemas), path re-prefixing, and REST query normalization + default-vs-max page size (working around pageSize being both the default and the hard ceiling). These would fit naturally in api/rest alongside openapi.ts, and would benefit any framework serving the spec — not just NestJS.
• NestJS-coupled glue (imports @nestjs/swagger) — the spec merge itself and an optional thin-controller helper. Can't live in core (no @nestjs/* deps there), so this would be a separate package.

Would you be open to taking the framework-agnostic helpers into api/rest? If a dedicated @zenstackhq/server/nest adapter is preferred instead, happy to scope that. Otherwise this stays a documentation-only contribution.

Notes

• Docs-only change; no code or public API affected.
• Links to the existing service/openapi/restful.md; only touches the current (v3) recipe, not the versioned 2.x docs.

Summary by CodeRabbit

• Documentation
  • Added a new NestJS guide showing how to reuse a shared API handler across multiple lightweight controllers.
  • Expanded Swagger documentation with an end-to-end setup for generating and merging OpenAPI output from ZenStack and NestJS.
  • Included a practical example for configuring Swagger with path prefix handling and document merging.

[vercel]

@lsmith77 is attempting to deploy a commit to the ZenStack Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Warning

Review limit reached

@lsmith77, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b31e3fb9-2f71-46df-b9cb-c0f8dcdc4691

📥 Commits

Reviewing files that changed from the base of the PR and between 09e0260 and 4c2bc31.

📒 Files selected for processing (1)

• docs/recipe/nestjs.md

Walkthrough

This PR adds documentation to docs/recipe/nestjs.md covering two NestJS integration patterns: sharing ZenStack's API handler across thin per-resource controllers via a shared service, and merging the generated ZenStack OpenAPI spec with NestJS's Swagger documentation.

Changes

NestJS Recipe Docs

Layer / File(s)	Summary
Shared handler across thin controllers docs/recipe/nestjs.md	Adds a section describing a shared RestHandlerService that forwards requests to RestApiHandler after stripping the /api prefix, with an example PostController delegating per-route calls to preserve NestJS metadata.
OpenAPI/Swagger merge example docs/recipe/nestjs.md	Adds a section with a setupSwagger example that generates the ZenStack OpenAPI spec, re-prefixes its paths, generates the NestJS Swagger document, merges paths and components.schemas (NestJS wins on conflicts), and calls SwaggerModule.setup.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Related PRs: None mentioned.

Suggested labels: documentation

Suggested reviewers: None specified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the docs update and highlights the main NestJS/Swagger OpenAPI merge guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/recipe/nestjs.md`:
- Around line 188-194: The request path passed from handleRequest to
RestApiHandler still keeps a leading slash after removing the /api prefix, which
can break resource-relative route matching. Update the relativePath handling in
handleRequest so it strips the leading slash as well before calling
this.apiHandler.handleRequest, and keep the change localized around the existing
req.path normalization logic.

🪄 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: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7ad7dbc9-6a86-479f-a1d2-cd84d0a001c3

📥 Commits

Reviewing files that changed from the base of the PR and between 703a707 and 09e0260.

📒 Files selected for processing (1)

• docs/recipe/nestjs.md