[O2B-1623] Document the shift-data endpoint in the HTTP API documentation (#2269)

* [O2B-1623] Document the shift data handler
* [O2B-1623] Document the shift-data endpoint in the HTTP API specification
* [O2B-1623] Regenerate the HTTP API documentation with the shift-data endpoint

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: graduta

lib/server/api-docs/API.md

@@ -350,3 +350,32 @@ Responses:
 ```bash
 curl -g "$BOOKKEEPING_URL/api/ctp-trigger-counters/106?token=$TOKEN"
 ```
+
+## Shifts
+
+Data used to fill end-of-shift reports.
+
+### `GET /shift-data` - Get the data of the pending shift of the calling user
+
+Operation id: `getShiftData`
+
+Returns what a shifter needs to write their end-of-shift (EoS) report for the **pending shift**: the current shift, or the previous one
+during the 30 minutes that follow its end. Shifts last 8 hours and are Night (23h-7h), Morning (7h-15h) and Afternoon (15h-23h) in the
+Geneva time zone. The shift is deduced from the current time and the calling user, not from a parameter.
+
+`typeSpecific` depends on `shiftType`: `{ environments }` for `ECS`, `{ runs }` for `QC/PDP`, `{ runs, tagsCounters }` for `SL`, and `null`
+for `SLIMOS` and `DCS`.
+
+| Parameter | In | Type | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `shiftType` | query | string | yes | Kind of shift. |
+
+Responses:
+
+- `200`: The shift data.
+- `400`: The request failed validation. HTTP status is 400 although each error's `status` field is `"422"`. `source.pointer` has the form `/data/attributes/<query|params|body>/<field>`.
+- `404`: The calling user is not known to Bookkeeping.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/shift-data?shiftType=ECS&token=$TOKEN"
+```

lib/server/api-docs/index.html

@@ -570,6 +570,44 @@ <h2>CTP trigger counters</h2>
 <pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/ctp-trigger-counters/106?token=$TOKEN&quot;
 </code></pre>
 </details>
+<h2>Shifts</h2>
+<p>Data used to fill end-of-shift reports.</p>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/shift-data</code> - Get the data of the pending shift of the calling user</h3></summary>
+
+<p>Operation id: <code>getShiftData</code></p>
+<p>Returns what a shifter needs to write their end-of-shift (EoS) report for the <strong>pending shift</strong>: the current shift, or the previous one
+during the 30 minutes that follow its end. Shifts last 8 hours and are Night (23h-7h), Morning (7h-15h) and Afternoon (15h-23h) in the
+Geneva time zone. The shift is deduced from the current time and the calling user, not from a parameter.</p>
+<p><code>typeSpecific</code> depends on <code>shiftType</code>: <code>{ environments }</code> for <code>ECS</code>, <code>{ runs }</code> for <code>QC/PDP</code>, <code>{ runs, tagsCounters }</code> for <code>SL</code>, and <code>null</code>
+for <code>SLIMOS</code> and <code>DCS</code>.</p>
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>In</th>
+<th>Type</th>
+<th>Required</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>shiftType</code></td>
+<td>query</td>
+<td>string</td>
+<td>yes</td>
+<td>Kind of shift.</td>
+</tr>
+</tbody></table>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: The shift data.</li>
+<li><code>400</code>: The request failed validation. HTTP status is 400 although each error&#39;s <code>status</code> field is <code>&quot;422&quot;</code>. <code>source.pointer</code> has the form <code>/data/attributes/&lt;query|params|body&gt;/&lt;field&gt;</code>.</li>
+<li><code>404</code>: The calling user is not known to Bookkeeping.</li>
+</ul>
+<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/shift-data?shiftType=ECS&amp;token=$TOKEN&quot;
+</code></pre>
+</details>
 
 </main>
 <footer>Generated from openapi.yaml by <code>npm run docs:api</code> · ALICE Bookkeeping · internal use only</footer>

lib/server/api-docs/openapi.yaml

@@ -47,6 +47,8 @@ tags:
     description: Types of runs (e.g. calibration kinds).
   - name: CTP trigger counters
     description: Counters of the central trigger processor, per run and trigger class.
+  - name: Shifts
+    description: Data used to fill end-of-shift reports.
 
 paths:
   /tags:
@@ -394,6 +396,37 @@ paths:
                 errors:
                   - { status: 404, title: Not found, detail: Run with this run number (999999999) could not be found }
 
+  /shift-data:
+    get:
+      tags: [Shifts]
+      operationId: getShiftData
+      summary: Get the data of the pending shift of the calling user
+      description: |
+        Returns what a shifter needs to write their end-of-shift (EoS) report for the **pending shift**: the current shift, or the previous one
+        during the 30 minutes that follow its end. Shifts last 8 hours and are Night (23h-7h), Morning (7h-15h) and Afternoon (15h-23h) in the
+        Geneva time zone. The shift is deduced from the current time and the calling user, not from a parameter.
+
+        `typeSpecific` depends on `shiftType`: `{ environments }` for `ECS`, `{ runs }` for `QC/PDP`, `{ runs, tagsCounters }` for `SL`, and `null`
+        for `SLIMOS` and `DCS`.
+      parameters:
+        - name: shiftType
+          in: query
+          required: true
+          description: Kind of shift.
+          schema: { type: string, enum: [ECS, QC/PDP, SLIMOS, SL, DCS], examples: [ECS] }
+      responses:
+        '200':
+          description: The shift data.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ShiftDataResponse' }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '404':
+          description: The calling user is not known to Bookkeeping.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
 components:
   securitySchemes:
     jwtQuery:
@@ -596,3 +629,43 @@ components:
         data:
           type: array
           items: { $ref: '#/components/schemas/CtpTriggerCounters' }
+    Shift:
+      type: object
+      required: [start, end, period]
+      properties:
+        start: { type: integer, description: Epoch milliseconds. }
+        end: { type: integer, description: Epoch milliseconds. }
+        period: { type: string, enum: [Night, Morning, Afternoon] }
+    ShiftData:
+      type: object
+      required: [shift, issuesLogs, typeSpecific, infoFromPreviousShifter]
+      properties:
+        shift: { $ref: '#/components/schemas/Shift' }
+        issuesLogs:
+          type: array
+          description: Log entries of the shift carrying the tags of the shift type, EoS reports excluded (see the Logs resource).
+          items: { type: object, additionalProperties: true }
+        typeSpecific:
+          type: [object, 'null']
+          description: Depends on the shift type, see the operation description.
+          properties:
+            environments: { type: array, description: 'ECS shift only.', items: { type: object, additionalProperties: true } }
+            runs:
+              type: object
+              description: QC/PDP and SL shifts only. Runs of the shift grouped by run definition.
+              additionalProperties: { type: array, items: { type: object, additionalProperties: true } }
+            tagsCounters:
+              type: object
+              description: SL shift only. Number of root logs of the shift per tag text, EoS reports excluded.
+              additionalProperties: { type: integer }
+        infoFromPreviousShifter:
+          type: object
+          description: The "For next shifter" section of the EoS report of the previous shift. Exactly one of the properties is set.
+          properties:
+            value: { type: string }
+            errorMessage: { type: string, description: 'Why nothing could be retrieved (no report, several reports, empty section...).' }
+    ShiftDataResponse:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: '#/components/schemas/ShiftData' }

lib/server/controllers/shift.controller.js

@@ -15,9 +15,14 @@ const { shiftService } = require('../services/shift/ShiftService.js');
 const { updateExpressResponseFromNativeError } = require('../express/updateExpressResponseFromNativeError.js');
 const { GetShiftDataDto } = require('../../domain/dtos/shift/GetShiftDataDto.js');
 
-// eslint-disable-next-line jsdoc/require-param
 /**
- * Route to fetch shift data
+ * Route to fetch the data of the pending shift of the calling user
+ *
+ * @param {Object} request The *request* object represents the HTTP request and has properties for the request query
+ *                         string, parameters, body, HTTP headers, and so on.
+ * @param {Object} response The *response* object represents the HTTP response that an Express app sends when it gets an
+ *                          HTTP request.
+ * @returns {Promise<void>} resolves once the response has been sent
  */
 const getShiftDataHandler = async (request, response) => {
     const requestDto = await dtoValidator(GetShiftDataDto, request, response);