docs(tasks): add OpenAPI YAML for tasks module API (#3389)

PierreBrisorgueil · web-flow · commit 92241aac7d24 · 2026-04-05T11:45:17.000+02:00
* docs(tasks): add OpenAPI YAML for tasks module API (#3386) Document all task endpoints (CRUD + stats) with request/response schemas, auth requirements, and path parameters. Add shared SuccessResponse and ErrorResponse schemas to core index for reuse across modules. * fix(tasks): address Copilot review — swagger merge, OpenAPI accuracy - initSwagger: use _.mergeWith to concatenate arrays (not index-merge) - initSwagger: guard empty file list, add filePath context on YAML errors - initSwagger: add JSDoc @param/@returns - tasks.yml: mark OrganizationId header deprecated with correct description - tasks.yml: add 422 response to GET /api/tasks - tasks.yml: update PUT description — both fields required, not partial - tasks.yml: document full DELETE response (id + acknowledged + deletedCount) - index.yml: add optional error field to ErrorResponse (non-prod only) * fix(swagger): guard YAML non-objects, seed reduce with {}, preserve error cause - Filter YAML.load results to plain objects (warn + skip null/array/primitive) - Pass initial {} to reduce so single-file configs merge correctly - Preserve original parse error as Error cause for better stack traces * fix(swagger): address CodeRabbit review — Unauthorized empty body, multi-module merge test - index.yml: Unauthorized response updated to reflect Passport JWT returns empty body (no JSON envelope) on 401 — matches actual runtime behavior - core.unit.tests.js: add test for multi-module YAML merge, asserting merged spec contains tasks paths and Task schema from modules/tasks/doc/tasks.yml * test(swagger): add branch coverage for empty file list, YAML error, and non-object YAML guard - Empty file list guard: verify initSwagger warns and skips route registration - YAML parse error: verify throw includes failing file path in message - Non-object YAML: verify scalar YAML files are skipped (filter(Boolean)) while valid files still produce a merged spec * test(swagger): fix async import in non-object YAML branch test Use async/await with dynamic import('fs') so the test works correctly in Jest's experimental VM modules ESM mode * fix(swagger): address CodeRabbit pass-2 — empty spec guard, partial update, PUT description - express.js: add guard after reduce — warn and skip route registration if all YAML files were filtered and spec is empty ({}) - tasks.service.js: fix update to only assign defined fields (partial update), aligning with Zod TaskUpdate = Task.partial() - tasks.yml: update PUT description to reflect actual partial-update behavior - core.unit.tests.js: add test for empty-spec guard (all YAMLs skipped → no routes)
diff --git a/MIGRATIONS.md b/MIGRATIONS.md
@@ -4,6 +4,23 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## OpenAPI Module Documentation (2026-04-04)
+
+Modules can now ship their own OpenAPI YAML in `modules/{name}/doc/{name}.yml`. These files are auto-discovered via the `modules/*/doc/*.yml` glob, merged into the base spec from `modules/core/doc/index.yml`, and served at `/api/spec.json` (+ Scalar UI at `/api/docs`).
+
+### What changed
+
+- `modules/core/doc/index.yml` — added shared component schemas (`SuccessResponse`, `ErrorResponse`) and reusable responses (`Unauthorized`, `Forbidden`, `NotFound`, `UnprocessableEntity`)
+- `modules/tasks/doc/tasks.yml` — reference OpenAPI doc for the tasks module (all CRUD + stats endpoints)
+
+### Action for downstream
+
+1. Run `/update-stack` to pull the change
+2. No breaking change — existing modules without a `doc/` folder are unaffected
+3. To document a custom module, create `modules/{name}/doc/{name}.yml` with paths, schemas, and tags
+
+---
+
 ## Scalar replaces swagger-ui-express (2026-04-04)
 
 `swagger-ui-express` has been removed. The API documentation UI is now powered by [Scalar](https://scalar.com/) via `@scalar/express-api-reference`.
diff --git a/lib/services/express.js b/lib/services/express.js
@@ -26,17 +26,57 @@ import analyticsMiddleware from '../middlewares/analytics.js';
 
 /**
  * Initialize API documentation (Scalar UI + JSON spec endpoint)
+ * @param {object} app - express application instance
+ * @returns {void}
  */
 const initSwagger = (app) => {
   if (config.swagger.enable) {
+    if (!config.files.swagger || config.files.swagger.length === 0) {
+      logger.warn('[swagger] no swagger files configured — skipping API docs');
+      return;
+    }
     // Merge all module OpenAPI YAML files into a single spec
-    const contents = config.files.swagger.map((filePath) => YAML.load(fs.readFileSync(filePath).toString()));
-    const spec = contents.reduce(_.merge);
+    // Use mergeWith to concatenate arrays (tags, servers, security) instead of merging by index
+    const contents = config.files.swagger
+      .map((filePath) => {
+        try {
+          const doc = YAML.load(fs.readFileSync(filePath).toString());
+          if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+            logger.warn(`[swagger] skipping ${filePath}: YAML did not parse to a plain object`);
+            return null;
+          }
+          return doc;
+        } catch (err) {
+          throw new Error(`[swagger] failed to load ${filePath}: ${err.message}`, { cause: err });
+        }
+      })
+      .filter(Boolean);
+    const spec = contents.reduce(
+      (acc, doc) =>
+        _.mergeWith(acc, doc, (objValue, srcValue) => {
+          if (Array.isArray(objValue)) return objValue.concat(srcValue);
+          return undefined;
+        }),
+      {},
+    );
 
-    // Serve the merged spec as JSON
-    app.get('/api/spec.json', (req, res) => {
+    if (Object.keys(spec).length === 0) {
+      logger.warn('[swagger] all YAML files were skipped — no valid spec to serve');
+      return;
+    }
+
+    /**
+     * Serve the merged OpenAPI spec as JSON.
+     * @param {import('express').Request} _req - Incoming request (unused).
+     * @param {import('express').Response} res - Express response.
+     * @returns {void}
+     */
+    const serveSpec = (_req, res) => {
       res.json(spec);
-    });
+    };
+
+    // Serve the merged spec as JSON
+    app.get('/api/spec.json', serveSpec);
 
     // Mount Scalar API reference UI
     app.use(
diff --git a/modules/core/doc/index.yml b/modules/core/doc/index.yml
@@ -9,3 +9,62 @@ components:
       type: "http"
       scheme: "bearer"
       bearerFormat: "JWT"
+
+  schemas:
+    SuccessResponse:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - success
+        message:
+          type: string
+        data:
+          description: Response payload (type varies by endpoint)
+
+    ErrorResponse:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - error
+        message:
+          type: string
+        code:
+          type: integer
+        status:
+          type: integer
+        errorCode:
+          type: string
+        description:
+          type: string
+        error:
+          type: string
+          description: JSON-stringified error details included only in non-production environments.
+
+  responses:
+    Unauthorized:
+      description: Missing or invalid JWT token — Passport JWT middleware returns 401 with an empty body (no JSON envelope)
+
+    Forbidden:
+      description: Insufficient permissions (CASL policy denied)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+
+    UnprocessableEntity:
+      description: Validation or business logic error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
diff --git a/modules/core/tests/core.unit.tests.js b/modules/core/tests/core.unit.tests.js
@@ -507,6 +507,37 @@ describe('Core unit tests:', () => {
         );
       });
 
+      it('should merge multiple module YAML files and include paths from each', () => {
+        config.swagger = { enable: true };
+        config.files = {
+          ...config.files,
+          swagger: [
+            path.join(process.cwd(), 'modules/core/doc/index.yml'),
+            path.join(process.cwd(), 'modules/tasks/doc/tasks.yml'),
+          ],
+        };
+        const mockGet = jest.fn();
+        const mockUse = jest.fn();
+        const mockApp = { get: mockGet, use: mockUse };
+        expressService.initSwagger(mockApp);
+        const handler = mockGet.mock.calls.find((c) => c[0] === '/api/spec.json')[1];
+        const mockRes = { json: jest.fn() };
+        handler({}, mockRes);
+        expect(mockRes.json).toHaveBeenCalledWith(
+          expect.objectContaining({
+            openapi: '3.0.0',
+            paths: expect.objectContaining({
+              '/api/tasks': expect.any(Object),
+            }),
+            components: expect.objectContaining({
+              schemas: expect.objectContaining({
+                Task: expect.any(Object),
+              }),
+            }),
+          }),
+        );
+      });
+
       it('should not register routes when swagger is disabled', () => {
         config.swagger = { enable: false };
         const mockGet = jest.fn();
@@ -516,6 +547,62 @@ describe('Core unit tests:', () => {
         expect(mockGet).not.toHaveBeenCalled();
         expect(mockUse).not.toHaveBeenCalled();
       });
+
+      it('should warn and skip registration when swagger file list is empty', () => {
+        config.swagger = { enable: true };
+        config.files = { ...config.files, swagger: [] };
+        const mockGet = jest.fn();
+        const mockUse = jest.fn();
+        const mockApp = { get: mockGet, use: mockUse };
+        expressService.initSwagger(mockApp);
+        expect(mockGet).not.toHaveBeenCalled();
+        expect(mockUse).not.toHaveBeenCalled();
+      });
+
+      it('should throw with file path context when a YAML file fails to load', () => {
+        config.swagger = { enable: true };
+        config.files = { ...config.files, swagger: ['/nonexistent/path/bad.yml'] };
+        const mockApp = { get: jest.fn(), use: jest.fn() };
+        expect(() => expressService.initSwagger(mockApp)).toThrow('[swagger] failed to load /nonexistent/path/bad.yml');
+      });
+
+      it('should skip YAML files that do not parse to a plain object and still register routes from valid ones', async () => {
+        // Write a temp YAML file that parses to a scalar string (not an object) — triggers the non-object guard
+        const { default: fsMod } = await import('fs');
+        const tmpFile = path.join('/tmp', `test-scalar-${Date.now()}.yml`);
+        fsMod.writeFileSync(tmpFile, 'just a string value\n');
+        try {
+          const validFile = path.join(process.cwd(), 'modules/core/doc/index.yml');
+          config.swagger = { enable: true };
+          config.files = { ...config.files, swagger: [tmpFile, validFile] };
+          const mockGet = jest.fn();
+          const mockUse = jest.fn();
+          const mockApp = { get: mockGet, use: mockUse };
+          expressService.initSwagger(mockApp);
+          expect(mockGet).toHaveBeenCalledWith('/api/spec.json', expect.any(Function));
+        } finally {
+          fsMod.unlinkSync(tmpFile);
+        }
+      });
+
+      it('should warn and skip registration when all YAML files produce an empty spec', async () => {
+        // Write a temp YAML file that parses to a scalar — after filter(Boolean), contents is empty → spec is {}
+        const { default: fsMod } = await import('fs');
+        const tmpFile = path.join('/tmp', `test-scalar-only-${Date.now()}.yml`);
+        fsMod.writeFileSync(tmpFile, 'just a string value\n');
+        try {
+          config.swagger = { enable: true };
+          config.files = { ...config.files, swagger: [tmpFile] };
+          const mockGet = jest.fn();
+          const mockUse = jest.fn();
+          const mockApp = { get: mockGet, use: mockUse };
+          expressService.initSwagger(mockApp);
+          expect(mockGet).not.toHaveBeenCalled();
+          expect(mockUse).not.toHaveBeenCalled();
+        } finally {
+          fsMod.unlinkSync(tmpFile);
+        }
+      });
     });
 
     describe('trust proxy', () => {
diff --git a/modules/tasks/doc/tasks.yml b/modules/tasks/doc/tasks.yml
diff --git a/modules/tasks/services/tasks.service.js b/modules/tasks/services/tasks.service.js
