From dd4ab1efb42530986d2bc6cb91a16c4b521c975c Mon Sep 17 00:00:00 2001
From: "Aaron K. Clark" <akclark@thenetwerk.net>
Date: Tue, 19 May 2026 13:52:20 -0500
Subject: [PATCH] docs(openapi): declare GET /v1/customer/bycompany/{id} 200
 envelope
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Same missing-content-schema pattern fixed for /v1/customer/{id}
in #312, POST /v1/customer in #316, POST /v1/timeentry in #326,
and POST /v1/customer/bulk in #332 — now for the paginated list
endpoint. The spec previously said only `description: 'OK'`, so
SDK generators reading the spec couldn't model the
Link-header-paired pagination envelope the controller emits:

    { message, count, limit, offset, customers: Customer[] }

Declare the shape and pin it with a test in
`tests/api/openapi.test.js`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 app/config/openapi.js     | 28 +++++++++++++++++++++++++++-
 tests/api/openapi.test.js | 19 +++++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/app/config/openapi.js b/app/config/openapi.js
index e836b3e..4ecd5be 100644
--- a/app/config/openapi.js
+++ b/app/config/openapi.js
@@ -700,7 +700,33 @@ const spec = {
                     { name: 'offset', in: 'query', schema: { type: 'integer', default: 0 } },
                 ],
                 responses: {
-                    200: { description: 'OK' },
+                    200: {
+                        description: 'OK — paginated customer list',
+                        // Controller wraps the rows in a {message, count,
+                        // limit, offset, customers} envelope. Same
+                        // missing-content-schema pattern fixed for the
+                        // single GET in #312 and the bulk POST in #332 —
+                        // now also for the paginated list. Without the
+                        // declaration, SDK generators can't model the
+                        // Link-header-paired pagination envelope.
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        message: { type: 'string' },
+                                        count: { type: 'integer' },
+                                        limit: { type: 'integer' },
+                                        offset: { type: 'integer' },
+                                        customers: {
+                                            type: 'array',
+                                            items: { $ref: '#/components/schemas/Customer' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
                     403: { description: 'Missing or invalid authKey' },
                 },
             },
diff --git a/tests/api/openapi.test.js b/tests/api/openapi.test.js
index 8026a01..53141f8 100644
--- a/tests/api/openapi.test.js
+++ b/tests/api/openapi.test.js
@@ -92,6 +92,25 @@ describe('OpenAPI spec', () => {
         expect(err.required).toEqual(['message']);
     });
 
+    test('GET /v1/customer/bycompany/{id} 200 declares the {message, count, limit, offset, customers} envelope', async () => {
+        // Paginated list endpoint — controller emits the same envelope
+        // every list endpoint uses. Pre-fix the spec said only
+        // `description: 'OK'`, so SDK generators couldn't model the
+        // shape clients see in response to a Link-header-paginated
+        // walk. Same missing-content-schema fix pattern as #316
+        // (single POST) and #332 (bulk POST).
+        const res = await request(app).get('/openapi.json');
+        const r200 = res.body.paths['/v1/customer/bycompany/{id}'].get.responses['200'];
+        const schema = r200.content['application/json'].schema;
+        expect(schema.type).toBe('object');
+        expect(schema.properties.message.type).toBe('string');
+        expect(schema.properties.count.type).toBe('integer');
+        expect(schema.properties.limit.type).toBe('integer');
+        expect(schema.properties.offset.type).toBe('integer');
+        expect(schema.properties.customers.type).toBe('array');
+        expect(schema.properties.customers.items.$ref).toBe('#/components/schemas/Customer');
+    });
+
     test('POST /v1/customer/bulk 201 declares the {message, count, customers} envelope', async () => {
         // makeBulkCreate (app/controllers/_bulk-helpers.js) emits
         // {message, count, <createdKey>}. The spec previously had