feat(openapi): legacy /api-docs-json alias for nuxt-base-starter compat (#60)

* test(openapi): add red tests for legacy /api-docs-json alias

Failing story tests covering:
- /api-docs-json passes the JWT middleware (public path)
- /api-docs-json passes the tenant guard (exempt path)
- GET /api-docs-json returns the same document as /api/openapi.json
- GET /api-docs-json sets Deprecation + Link successor-version headers

Drives the upcoming bootstrap shim that keeps older nuxt-base-starter
installations (whose openapi-ts.config.ts fallback hardcodes
/api-docs-json) working until lenneTech/nuxt-base-starter#13 ships.

* feat(openapi): legacy /api-docs-json alias for nuxt-base-starter compat

Mounts /api-docs-json as a deprecated alias of /api/openapi.json so
older nuxt-base-starter installations (whose openapi-ts.config.ts
fallback hardcodes the legacy path) keep generating types without
manual config edits.

The handler returns the same OpenAPI document plus RFC 8594
`Deprecation` and RFC 8288 `Link: rel="successor-version"` headers
pointing clients at the canonical URL. Path is added to the JWT
middleware and tenant-guard exempt sets so the Express-mounted
shim mirrors `/api/openapi.json`'s public-access posture.

Tracked upstream at lenneTech/nuxt-base-starter#13
— remove this shim once the fix has propagated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(architecture): note legacy /api-docs-json alias + deprecation timeline

Adds a short paragraph under "Zod → OpenAPI bridge" pointing at the
canonical /api/openapi.json URL and explaining the deprecated
/api-docs-json alias plus the upstream issue
(lenneTech/nuxt-base-starter#13) gating its removal.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Ralph Loop <ralph@local>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

docs/architecture.md

@@ -209,6 +209,17 @@ The slim-module reference and the user-profile module are the two
 canonical examples — copy their decorator pattern when you scaffold
 a new module.
 
+`/api/openapi.json` is the canonical OpenAPI doc URL.
+`/api-docs-json` is mounted as a **deprecated alias** for legacy
+`nuxt-base-starter` installations whose `openapi-ts.config.ts`
+fallback still hardcodes the path used by older
+`nest-server-starter` releases. The alias returns the same document
+plus `Deprecation` (RFC 8594) and `Link: rel="successor-version"`
+(RFC 8288) headers pointing clients at the canonical URL. It will
+be removed once the upstream fix
+([lenneTech/nuxt-base-starter#13](https://github.com/lenneTech/nuxt-base-starter/issues/13))
+has propagated to all consumer workspaces.
+
 ## Multi-tenancy
 
 Two-layer isolation:

src/core/app/bootstrap.ts

@@ -119,6 +119,22 @@ export async function bootstrap(options: BootstrapOptions = {}): Promise<INestAp
   app.use("/api/openapi.json", (_req: any, res: any) => {
     res.json(openApiDocument);
   });
+  // Legacy alias for `nuxt-base-starter` installations whose
+  // `openapi-ts.config.ts` fallback still hardcodes `/api-docs-json`
+  // (the path used by older versions of `nest-server-starter`).
+  // Tracked upstream at
+  // https://github.com/lenneTech/nuxt-base-starter/issues/13;
+  // remove once that fix has propagated to all consumer workspaces.
+  // The `Deprecation` (RFC 8594) + `Link` (RFC 8288, `successor-version`)
+  // headers tell well-behaved clients to migrate to /api/openapi.json.
+  //
+  // @deprecated use /api/openapi.json
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  app.use("/api-docs-json", (_req: any, res: any) => {
+    res.setHeader("Deprecation", "Sat, 31 Oct 2026 23:59:59 GMT");
+    res.setHeader("Link", '</api/openapi.json>; rel="successor-version"');
+    res.json(openApiDocument);
+  });
   if (cfg.env !== "production") {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     app.use("/api/openapi", (req: any, res: any, next: any) => {

src/core/auth/jwt-middleware.ts

@@ -14,9 +14,14 @@
  * `/api/openapi.json` serve the OpenAPI spec the SDK generators read.
  * Both are dev-friendly (they expose error codes / route shapes only,
  * never user data) and intentionally outside the auth wall.
+ *
+ * `/api-docs-json` is the deprecated legacy alias for the OpenAPI
+ * doc, kept exempt for the same reason as `/api/openapi.json` until
+ * the upstream `nuxt-base-starter` fix
+ * (lenneTech/nuxt-base-starter#13) has propagated.
  */
 const PUBLIC_PREFIXES = ["/health/", "/api/auth/", "/docs/", "/dev/", "/errors/", "/api/openapi"];
-const PUBLIC_EXACT = new Set(["/", "/errors", "/api/openapi"]);
+const PUBLIC_EXACT = new Set(["/", "/errors", "/api/openapi", "/api-docs-json"]);
 
 export function isPathProtected(path: string): boolean {
   if (!path) throw new Error("isPathProtected: path is required");

src/core/multi-tenancy/tenant-guard.ts

@@ -8,7 +8,12 @@
  * The actual NestJS Guard wraps this classifier in a future slice.
  */
 
-const EXEMPT_EXACT = new Set(["/", "/errors", "/tenants"]);
+// `/api-docs-json` is the deprecated legacy alias for
+// `/api/openapi.json` — exempt from the tenant header because SDK
+// generators that hit the legacy URL don't carry a tenant context
+// (mirrors the canonical doc's exemption). Removed once
+// lenneTech/nuxt-base-starter#13 has propagated.
+const EXEMPT_EXACT = new Set(["/", "/errors", "/tenants", "/api-docs-json"]);
 // `/me/*` endpoints operate on the authenticated user (req.user.id),
 // not on a specific tenant. `/tenants` is the self-service tenant CRUD
 // surface — a signed-up user creates their first tenant here, so the

tests/stories/openapi-legacy-alias.story.test.ts

@@ -0,0 +1,72 @@
+import type { INestApplication } from "@nestjs/common";
+import request from "supertest";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { isPathProtected } from "../../src/core/auth/jwt-middleware.js";
+import { isTenantExempt } from "../../src/core/multi-tenancy/tenant-guard.js";
+import { bootstrap } from "../../src/core/app/bootstrap.js";
+
+const SILENT_LOGGER = { log() {}, warn() {}, error() {}, debug() {}, verbose() {} };
+
+/**
+ * Story · Legacy `/api-docs-json` alias.
+ *
+ * Older `nuxt-base-starter` workspaces hard-code
+ * `http://127.0.0.1:3000/api-docs-json` in their `openapi-ts.config.ts`
+ * fallback. Since this server canonicalised the OpenAPI doc at
+ * `/api/openapi.json`, those workspaces 401 on `pnpm run generate-types`
+ * until they upgrade. We mount `/api-docs-json` as a deprecated alias
+ * that returns the exact same document plus `Deprecation` /
+ * `Link: rel="successor-version"` headers, buying time until the
+ * upstream fix (lenneTech/nuxt-base-starter#13) propagates.
+ *
+ * Tracked at https://github.com/lenneTech/nuxt-base-starter/issues/13.
+ */
+describe("Story · Legacy /api-docs-json alias", () => {
+  describe("auth + tenant exemptions", () => {
+    it("treats /api-docs-json as public (no JWT required)", () => {
+      expect(isPathProtected("/api-docs-json")).toBe(false);
+    });
+
+    it("treats /api-docs-json as tenant-exempt", () => {
+      expect(isTenantExempt("/api-docs-json")).toBe(true);
+    });
+  });
+
+  describe("HTTP behaviour", () => {
+    let app: INestApplication;
+
+    beforeAll(async () => {
+      app = await bootstrap({ listen: false, logger: SILENT_LOGGER });
+    });
+
+    afterAll(async () => {
+      await app?.close();
+    });
+
+    it("returns the same OpenAPI document as /api/openapi.json", async () => {
+      const canonical = await request(app.getHttpServer()).get("/api/openapi.json");
+      const legacy = await request(app.getHttpServer()).get("/api-docs-json");
+      expect(canonical.status).toBe(200);
+      expect(legacy.status).toBe(200);
+      // Compare the structural body — both endpoints serve the same
+      // SwaggerModule document instance, so deep equality must hold.
+      expect(legacy.body).toEqual(canonical.body);
+      expect(legacy.body?.openapi).toBeDefined();
+      expect(legacy.body?.paths).toBeDefined();
+    });
+
+    it("sends a Deprecation header pointing clients at the canonical URL", async () => {
+      const res = await request(app.getHttpServer()).get("/api-docs-json");
+      expect(res.status).toBe(200);
+      // RFC 8594 — Deprecation header signals to clients (and human
+      // log-readers) that the endpoint is on its way out.
+      expect(res.headers.deprecation).toBeDefined();
+      // RFC 8288 Link header with rel="successor-version" points at
+      // /api/openapi.json. SDK generators that respect the hint can
+      // self-heal without a config change.
+      expect(res.headers.link).toContain("</api/openapi.json>");
+      expect(res.headers.link).toContain('rel="successor-version"');
+    });
+  });
+});