[O2B-1623] Document the detectors endpoint in the HTTP API documentation

lib/database/adapters/DetectorAdapter.js

@@ -30,13 +30,11 @@ class DetectorAdapter {
      * @param {SequelizeDetector} databaseObject Object to convert.
      * @returns {Detector} Converted entity object.
      */
-    toEntity({ id, name, type, createdAt, updatedAt }) {
+    toEntity({ id, name, type }) {
         return {
             id,
             name,
             type,
-            createdAt: new Date(createdAt).getTime(),
-            updatedAt: new Date(updatedAt).getTime(),
         };
     }
 

lib/domain/entities/Detector.js

@@ -14,8 +14,7 @@
 /**
  * @typedef Detector
  *
+ * @property {number} id
  * @property {string} name
  * @property {'PHYSICAL'|'QC'|'VIRTUAL'|'OTHER'} type
- * @property {number} createdAt
- * @property {number} updatedAt
  */

lib/server/api-docs/API.md

@@ -269,3 +269,21 @@ Responses:
 ```bash
 curl -g "$BOOKKEEPING_URL/api/configuration?token=$TOKEN"
 ```
+
+## Detectors
+
+Detectors of the ALICE experiment.
+
+### `GET /detectors` - List all detectors
+
+Operation id: `listDetectors`
+
+Returns every detector, sorted alphabetically by name. Not paginated.
+
+Responses:
+
+- `200`: The detectors.
+
+```bash
+curl -g "$BOOKKEEPING_URL/api/detectors?token=$TOKEN"
+```

lib/server/api-docs/index.html

@@ -474,6 +474,20 @@ <h2>Configuration</h2>
 <pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/configuration?token=$TOKEN&quot;
 </code></pre>
 </details>
+<h2>Detectors</h2>
+<p>Detectors of the ALICE experiment.</p>
+<details>
+<summary><h3><span class="method get">GET</span> <code>/detectors</code> - List all detectors</h3></summary>
+
+<p>Operation id: <code>listDetectors</code></p>
+<p>Returns every detector, sorted alphabetically by name. Not paginated.</p>
+<p>Responses:</p>
+<ul>
+<li><code>200</code>: The detectors.</li>
+</ul>
+<pre><code class="language-bash">curl -g &quot;$BOOKKEEPING_URL/api/detectors?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

@@ -41,6 +41,8 @@ tags:
     description: Health of the Bookkeeping application and of its database.
   - name: Configuration
     description: Addresses of the external services Bookkeeping links to.
+  - name: Detectors
+    description: Detectors of the ALICE experiment.
 
 paths:
   /tags:
@@ -291,6 +293,23 @@ paths:
                   QcGuiUrl: http://localhost:8082
                   AliEcsGuiUrl: http://localhost:8080
 
+  /detectors:
+    get:
+      tags: [Detectors]
+      operationId: listDetectors
+      summary: List all detectors
+      description: Returns every detector, sorted alphabetically by name. Not paginated.
+      responses:
+        '200':
+          description: The detectors.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/DetectorListResponse' }
+              example:
+                data:
+                  - { id: 17, name: ACO, type: PHYSICAL }
+                  - { id: 21, name: GLO, type: QC }
+
 components:
   securitySchemes:
     jwtQuery:
@@ -436,3 +455,20 @@ components:
             AliFlpIndexUrl: { type: [string, 'null'], description: ali-flp-index page. }
             QcGuiUrl: { type: [string, 'null'], description: Quality Control GUI. }
             AliEcsGuiUrl: { type: [string, 'null'], description: AliECS GUI. }
+    Detector:
+      type: object
+      required: [id, name, type]
+      properties:
+        id: { type: integer }
+        name: { type: string, description: 'Detector code, e.g. `ITS`.' }
+        type:
+          type: string
+          enum: [PHYSICAL, QC, AOT-GLO, AOT-EVENT, MUON-GLO, VIRTUAL, OTHER]
+          description: Kind of detector. Only `PHYSICAL` and `VIRTUAL` detectors can take part in data taking.
+    DetectorListResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items: { $ref: '#/components/schemas/Detector' }

test/api/detectors.test.js

@@ -25,6 +25,7 @@ module.exports = () => {
 
             expect(response.status).to.equal(200);
             expect(response.body).to.be.an('object');
+            response.body.data.forEach((detector) => expect(Object.keys(detector)).to.have.members(['id', 'name', 'type']));
             expect(response.body.data.map(({ id, name }) => ({ id, name }))).to.deep.eq([
                 { id: 17, name: 'ACO' },
                 { id: 1, name: 'CPV' },