@vida-global/core 2.3.1 → 2.3.2

package/lib/server/doc/documentation.md

@@ -56,9 +56,18 @@ Responses with a status `>= 400` additionally document an `errors` object (`{ me
 
 Parameters and request bodies are **derived automatically** from the action's `parametersFor<ActionName>` validator definitions (see [Validations](./validations.md)) — there is no need to repeat them in YAML. Each declared parameter is placed by location:
 
-- **Path parameters** — any parameter whose name appears in the route (e.g. `:id`). Always required.
+- **Path parameters** — every placeholder in the route (e.g. `:id`). Always required. A matching
+  validator definition supplies its schema; otherwise it defaults to a string.
 - **Query parameters** — for `GET`/`DELETE` actions, or any parameter marked `{ queryParameter: true }`.
-- **Request body** — for `POST`/`PUT` actions, declared params become a `requestBody` object schema; non-`optional` params are listed as `required`. The body defaults to `application/json`, but switches to `multipart/form-data` automatically when any body param declares `{ format: 'binary' }` (rendered as `{ type: 'string', format: 'binary' }` — the standard way to document a file upload).
+- **Request body** — for `POST`/`PUT`/`PATCH` actions, declared params become a
+  `requestBody` object schema;
+  non-`optional` params are listed as `required`. The body defaults to `application/json`, but
+  switches to `multipart/form-data` automatically when any body param declares
+  `{ format: 'binary' }` (rendered as `{ type: 'string', format: 'binary' }` — the standard way to
+  document a file upload).
+
+An action YAML file may provide a complete `requestBody` for an exceptional `POST`, `PUT`, or
+`PATCH` transport contract.
 
 The validator definition itself becomes the parameter's JSON schema, and `example`, `default`, `format`, and `nullable` pass through when present. Set `{ nullable: true }` to document a value that may be `null`.
 
@@ -73,6 +82,26 @@ static parametersForPostImport() {
 }
 ```
 
+When middleware provides a body field that is not available through controller parameters, the
+action YAML may provide a complete OpenAPI `requestBody`. The explicit definition replaces inferred
+body documentation for that action:
+
+```yaml
+summary: Upload a file
+description: Uploads one file.
+requestBody:
+  required: true
+  content:
+    multipart/form-data:
+      schema:
+        type: object
+        required: [file]
+        properties:
+          file:
+            type: string
+            format: binary
+```
+
 
 ## Tags
 

package/lib/server/openApi/apiDocGenerator.js

@@ -263,6 +263,8 @@ class ApiDocGenerator {
 
 
     get requestBody() {
+        if (this.#details.requestBody) return structuredClone(this.#details.requestBody);
+
         const properties = this.bodyProperties;
         if (!Object.keys(properties).length) return undefined;
 
@@ -289,15 +291,18 @@ class ApiDocGenerator {
 
 
     get pathParams() {
-        const params = this.#allRequestInputs.filter(([name, _]) => this.#pathParamNames.includes(name));
-        return this.#formatInputs(Object.fromEntries(params), 'path');
+        const params = {};
+        for (const name of this.#pathParamNames) {
+            params[name] = this.#requestInputsByName[name] || { isString: true };
+        }
+        return this.#formatInputs(params, 'path');
     }
 
 
     get queryParams() {
         const params = this.#allRequestInputs.filter(([name, details]) => {
             if (this.#pathParamNames.includes(name)) return false;
-            if (details?.queryParameter === true)         return true;
+            if (details?.queryParameter === true) return true;
             return this.method == 'get' || this.method == 'delete';
         });
         return this.#formatInputs(Object.fromEntries(params), 'query');
@@ -305,9 +310,10 @@ class ApiDocGenerator {
 
 
     get bodyProperties() {
-        const inputs = this.#allRequestInputs.filter(([name, _]) => {
+        const inputs = this.#allRequestInputs.filter(([name, details]) => {
             if (this.#pathParamNames.includes(name)) return false;
-            return this.method == 'post' || this.method == 'put';
+            if (details?.queryParameter === true) return false;
+            return ['post', 'put', 'patch'].includes(this.method);
         });
         return this.#formatInputs(Object.fromEntries(inputs), 'body');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.3.1",
+    "version": "2.3.2",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",

package/test/server/apiDocGenerator.test.js

@@ -126,6 +126,29 @@ describe('ApiDocGenerator', () => {
             });
         });
 
+        it ('documents every route placeholder when no validator definition exists', () => {
+            const action = { action: 'getRecord', method: 'GET', path: '/account/:accountId/job/:jobId' };
+            ControllerClass.parametersForAction.mockReturnValue({});
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.pathParams).toEqual({
+                accountId: {
+                    name:        'accountId',
+                    in:          'path',
+                    required:    true,
+                    description: '',
+                    schema:      { type: 'string' },
+                },
+                jobId: {
+                    name:        'jobId',
+                    in:          'path',
+                    required:    true,
+                    description: '',
+                    schema:      { type: 'string' },
+                },
+            });
+        });
+
         it ('marks path params required even when the definition is optional', () => {
             const action = { action: 'getRecord', method: 'GET', path: '/user/:id' };
             ControllerClass.parametersForAction.mockReturnValue({ id: { isString: true, optional: true } });
@@ -190,6 +213,7 @@ describe('ApiDocGenerator', () => {
 
             expect(Object.keys(generator.queryParams)).toEqual(['detail']);
         });
+
     });
 
 
@@ -217,6 +241,20 @@ describe('ApiDocGenerator', () => {
 
             expect(generator.bodyProperties).toEqual({});
         });
+
+        it ('builds body properties for PATCH actions', () => {
+            const action = { action: 'patchRecord', method: 'PATCH', path: '/things/:id' };
+            ControllerClass.parametersForAction.mockReturnValue({
+                id:   { isInteger: true },
+                name: { isString: true },
+            });
+            const generator = new ApiDocGenerator(action, ControllerClass);
+
+            expect(generator.bodyProperties).toEqual({
+                name: { type: 'string', description: '' },
+            });
+        });
+
     });
 
 
@@ -620,6 +658,29 @@ describe('ApiDocGenerator', () => {
             });
         });
 
+        it ('uses an explicit requestBody from action YAML for middleware-backed input', () => {
+            const requestBody = {
+                required: true,
+                content: {
+                    'multipart/form-data': {
+                        schema: {
+                            type:       'object',
+                            properties: {
+                                file: { type: 'string', format: 'binary' },
+                            },
+                            required: ['file'],
+                        },
+                    },
+                },
+            };
+            const generator = documented({
+                details: { requestBody },
+                params:  { path: { isString: true } },
+            });
+
+            expect(generator.documentation.requestBody).toEqual(requestBody);
+        });
+
         it ('includes security when the action is authenticated', () => {
             const generator = documented({ params: {}, security: [{ apiKeyAuth: [] }] });